Preview subscription renewal
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).
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 subscriptionGET /subscriptions— List subscriptionsGET /subscriptions/{id}— Get subscription by IDPATCH /subscriptions/{id}— Update subscription detailsDELETE /subscriptions/{id}— Delete subscriptionPOST /subscriptions/{id}/change-plan— Change subscription planPOST /subscriptions/{id}/change-quantity— Change subscription quantityPOST /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 aWWW-Authenticate: Bearerchallenge.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.
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
Subscription UUID
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.revkeen.com/v2/subscriptions/00000000-0000-0000-0000-000000000000/preview-renewal" \
-H "x-api-key: $REVKEEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"previewCount": 3
}'{ "data": { "subscriptionId": "d079718b-ff63-45dd-947b-4950c023750f", "currentPeriodEnd": "2019-08-24T14:15:22Z", "upcomingRenewals": [ { "sequence": 1, "date": "2019-08-24T14:15:22Z", "formattedDate": "string", "dayName": "string", "amountMinor": 0, "formattedAmount": "string", "isTrialEnd": true, "isFirstCharge": true, "isFinalPayment": true } ], "nextInvoiceAmountMinor": 0, "currency": "str" }}Pause subscription POST
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).
Reactivate subscription POST
Reverse a scheduled cancellation. The subscription must be active with cancelAtPeriodEnd=true. Clears the cancellation flag and the subscription continues as normal. --- **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).