RevKeenDocs
StatusSupport
API Reference

Generate billing schedule preview

Generate a preview of upcoming billing dates and amounts based on the provided schedule configuration. This endpoint uses the same billing calculation logic as the actual scheduler, ensuring that the preview matches what will actually be billed (Key Invariant #4: Preview === Scheduler). Use this to show customers their expected billing schedule before they subscribe, or to preview changes to an existing subscription's billing configuration. --- **Related endpoints** - `GET /billing/intervals` — Get billing intervals - `GET /billing/anchor-rules` — Get billing anchor rules **Common errors** - `400 invalid_request` — malformed payload or failed validation. **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
/billing/preview

Generate a preview of upcoming billing dates and amounts based on the provided schedule configuration.

This endpoint uses the same billing calculation logic as the actual scheduler, ensuring that the preview matches what will actually be billed (Key Invariant #4: Preview === Scheduler).

Use this to show customers their expected billing schedule before they subscribe, or to preview changes to an existing subscription's billing configuration.

Related endpoints

  • GET /billing/intervals — Get billing intervals
  • GET /billing/anchor-rules — Get billing anchor rules

Common errors

  • 400 invalid_request — malformed payload or failed validation.

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

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/billing/preview" \
  -H "x-api-key: $REVKEEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interval": "day"
  }'
{  "data": {    "items": [      {        "sequence": 1,        "date": "2019-08-24T14:15:22Z",        "formattedDate": "string",        "dayName": "string",        "amountMinor": 0,        "formattedAmount": "string",        "isTrialEnd": true,        "isFirstCharge": true,        "isFinalPayment": true      }    ],    "summary": "string",    "totalAmountMinor": 0,    "firstChargeDate": "2019-08-24T14:15:22Z",    "trialEndDate": "2019-08-24T14:15:22Z",    "scheduleEndDate": "2019-08-24T14:15:22Z",    "timezone": "string"  }}

Get billing intervals GET

Get the list of supported billing intervals and their display labels. --- **Related endpoints** - `POST /billing/preview` — Generate billing schedule preview - `GET /billing/anchor-rules` — Get billing anchor rules **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.

Ensure managed Cart API keys exist POST

Creates any missing managed RevKeen Cart publishable and secret keys for the authenticated merchant. Newly created key values are returned once; existing secret values are never re-exposed. --- **Related endpoints** - `GET /cart-api-keys/status` — Get managed Cart API key status - `POST /cart-api-keys/{kind}/rotate` — Rotate a managed Cart API key **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. - `403 authorization_error` — the caller is identified but the action is denied. Codes include `insufficient_permissions`, `ip_not_allowed`, `merchant_mismatch`, and `origin_not_allowed`. **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).