Create a new subscription
Create a new subscription for a customer --- **Related endpoints** - `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 - `POST /subscriptions/{id}/pause` — Pause subscription **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. **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).
Create a new subscription for a customer
Related endpoints
GET /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}/preview-renewal— Preview subscription renewalPOST /subscriptions/{id}/pause— Pause subscription
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 aWWW-Authenticate: Bearerchallenge.
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
Request 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" \
-H "x-api-key: $REVKEEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customerId": "00000000-0000-0000-0000-000000000000"
}'{ "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 } }}Change subscription quantity POST
Update the quantity for a subscription with optional proration --- **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}/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. - `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).
Delete subscription DELETE
Cancel an active subscription immediately or at period end --- **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 - `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. - `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).