RevKeenDocs
StatusSupport
API Reference

Pause subscription

Pause an active subscription. While paused: - No new invoices are generated - The subscription status changes to "paused" - The customer retains access until the current period ends (depending on your business logic) **Behavior Options:** - `keep_as_draft`: Invoices are created as drafts (default) - `mark_uncollectible`: Invoices are marked uncollectible - `void`: Invoices are voided Optionally set `resumes_at` to automatically resume at a future date. --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 authentication_error` — missing, invalid, expired, or revoked credential. Codes: `authentication_failed`, `invalid_api_key`, `expired_api_key`, `api_key_revoked`, `session_invalid`, `merchant_required`. Carries a `WWW-Authenticate: Bearer` challenge. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency).

POST
/subscriptions/{id}/pause

Pause an active subscription. While paused:

  • No new invoices are generated
  • The subscription status changes to "paused"
  • The customer retains access until the current period ends (depending on your business logic)

Behavior Options:

  • keep_as_draft: Invoices are created as drafts (default)
  • mark_uncollectible: Invoices are marked uncollectible
  • void: Invoices are voided

Optionally set resumes_at to automatically resume at a future date.

Related endpoints

  • POST /subscriptions — Create a new subscription
  • GET /subscriptions — List subscriptions
  • GET /subscriptions/{id} — Get subscription by ID
  • PATCH /subscriptions/{id} — Update subscription details
  • DELETE /subscriptions/{id} — Delete subscription
  • POST /subscriptions/{id}/change-plan — Change subscription plan
  • POST /subscriptions/{id}/change-quantity — Change subscription quantity
  • POST /subscriptions/{id}/preview-renewal — Preview subscription renewal

Common errors

  • 400 invalid_request — malformed payload or failed validation.
  • 401 authentication_error — missing, invalid, expired, or revoked credential. Codes: authentication_failed, invalid_api_key, expired_api_key, api_key_revoked, session_invalid, merchant_required. Carries a WWW-Authenticate: Bearer challenge.
  • 404 resource_missing — the referenced resource does not exist or is not visible to your key.

Idempotency

Pass an Idempotency-Key header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see the idempotency guide.

Authorization

x-api-key<token>

Your RevKeen merchant API key. Create and manage keys in Dashboard → Settings → Developer. Use rk_sandbox_* for staging/test and rk_live_* for production. The same key may be sent as Authorization: Bearer <key> if that suits your HTTP client better. A missing, invalid, expired, or revoked key returns 401 with a WWW-Authenticate: Bearer challenge; a valid key without the required scope returns 403.

In: header

Path Parameters

id*string

Subscription UUID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Parameters for pausing an active subscription. Specify when billing should resume.

Response Body

application/json

application/json

application/json

application/json

application/json

Stuck on an error response? Ask the RevKeen assistant to explain it.
curl -X POST "https://api.revkeen.com/v2/subscriptions/00000000-0000-0000-0000-000000000000/pause" \
  -H "x-api-key: $REVKEEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "behavior": "keep_as_draft",
    "resumes_at": "2024-02-15T00:00:00Z"
  }'
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",    "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",    "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",    "price_id": "5eff5d89-979e-4e4f-aa76-6cbbbf11362c",    "plan_id": "00713021-9aea-41da-9a88-87760c08fa72",    "status": "string",    "quantity": 0,    "amount_minor": 0,    "currency": "string",    "billing_interval": "string",    "current_period_start": "2019-08-24T14:15:22Z",    "current_period_end": "2019-08-24T14:15:22Z",    "trial_end": "2019-08-24T14:15:22Z",    "canceled_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "dunning": {      "is_in_dunning": true,      "phase": 0,      "phase_label": "string",      "phase_severity": "info",      "retry_count": 0,      "total_possible_retries": 0,      "next_retry_at": "2019-08-24T14:15:22Z",      "days_in_dunning": 0,      "access_restricted": true    }  }}

List subscriptions GET

Retrieve a paginated list of subscriptions with optional filters --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 authentication_error` — missing, invalid, expired, or revoked credential. Codes: `authentication_failed`, `invalid_api_key`, `expired_api_key`, `api_key_revoked`, `session_invalid`, `merchant_required`. Carries a `WWW-Authenticate: Bearer` challenge. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers.

Preview subscription renewal POST

Preview the upcoming renewal dates and amounts for an existing subscription. This uses the same billing calculation logic as the actual scheduler to show exactly when and how much the subscription will be billed (Key Invariant #4: Preview === Scheduler). --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 authentication_error` — missing, invalid, expired, or revoked credential. Codes: `authentication_failed`, `invalid_api_key`, `expired_api_key`, `api_key_revoked`, `session_invalid`, `merchant_required`. Carries a `WWW-Authenticate: Bearer` challenge. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency).