Create a new subscription

Create a new subscription for a customer.

The first period is billed at creation, at the price's amount for the quantity. On card the saved paymentMethodId is charged straight away (it is required unless the subscription starts in a trial). On Direct Debit the first collection is scheduled with advance notice, typically 5–7 working days after creation. With a trial, nothing is billed until the trial ends. A trial starts from trialEnd, from trial_period_days, or, when the request names neither, from the price's own trial_period_days; send trial_period_days: 0 to start without the price's trial. trialEnd and trial_period_days cannot be combined (400 trial_conflict).

Set paymentRail: direct_debit with an active mandateId to create a Direct Debit subscription (GBP only). This needs a signed-in team member or an OAuth app; API keys are refused with 403.

---

Related endpoints

• 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}/preview-change-plan — Preview a plan change
• POST /subscriptions/{id}/pause — Pause subscription
• POST /subscriptions/{id}/resume — Resume subscription
• POST /subscriptions/{id}/cancel — Cancel 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.
• 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.
• 404 resource_missing — the referenced resource does not exist or is not visible to your key.
• 422 unprocessable_entity — business-rule failure (for example, refunding more than the original charge).

Idempotency

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

Response Body

curl -X POST "https://api.revkeen.com/v2/subscriptions" \
  -H "x-api-key: $REVKEEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "11111111-1111-4111-8111-111111111111"
  }'

{  "data": {    "id": "d4e6f8a1-2b3c-4d5e-9f60-7a8b9c0d1e24",    "merchant_id": "8f14e45f-ceea-4e7a-9b4b-7c3f1a2d5e60",    "customer_id": "c2a1e7d4-5b3f-4a8e-9d21-6f0b3e4c7a11",    "product_id": "a7b3c9d2-1e4f-4b6a-8c5d-2f9e0a1b3c42",    "price_id": "b5d8e2f1-3a6c-4d9b-8e7f-1c4a2b5d6e73",    "plan_id": null,    "status": "active",    "quantity": 1,    "amount_minor": 4900,    "currency": "GBP",    "billing_interval": "month",    "current_period_start": "2026-04-16T10:00:00.000Z",    "current_period_end": "2026-05-16T10:00:00.000Z",    "trial_end": "2026-04-16T10:00:00.000Z",    "canceled_at": null,    "created_at": "2026-04-02T10:00:00.000Z",    "updated_at": "2026-04-02T10:05:00.000Z",    "dunning": null,    "payment_rail": "card",    "mandate_id": null,    "payment_method_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c65"  }}