Create a new subscription
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 unauthenticated— missing, malformed, or revoked API key.
Idempotency
Pass an Idempotency-Key header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see the idempotency guide.
x-api-key<token>
Your RevKeen API key (powered by Unkey). Get it from Dashboard > Settings > API Keys. Use rk_sandbox_* for test mode and rk_live_* for production.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
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" \
-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
}
}
}{
"error": "Bad request"
}{
"error": "Unauthorized"
}