Skip to content
Creative Payments

Subscriptions

A subscription charges a buyer the same amount on a fixed schedule, for example every month, without the buyer paying each time. The buyer pays a first payment once; that gives the mandate for the charges that follow.

On this page

Concepts

  • Subscription (sub_...): the amount, currency, interval and number of charges agreed with one buyer.
  • First payment: an ordinary payment the buyer pays now, with subscription_id set. Paying it gives the mandate.
  • Mandate: the buyer’s agreement that lets the same method be charged again without the buyer doing anything.
  • Recurring charge: a payment created for the subscription on each interval. The buyer does not pay it on a page.

The flow

  1. You create the subscription with POST /v1/subscriptions. It is pending_mandate, and the answer carries its first payment.
  2. The buyer pays the first payment, on its checkout or with a method you select through the direct API.
  3. When the first payment is paid, the subscription becomes active and you get subscription.activated.
  4. On every interval the buyer is charged. Each charge is a payment with subscription_id set, reported with the usual payment.* events.
  5. It ends when all its charges are made (completed) or when you cancel it (canceled). A first payment that fails or expires ends it at once (abandoned).

Before you start

Create a subscription

Create a subscriptioncurl
curl -sS https://payments.example.com/api/v1/subscriptions \
  -H "Authorization: Bearer cp_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sub-customer-17-plus" \
  -d '{
    "amount": "49.00",
    "currency": "EUR",
    "interval": "1 month",
    "times": 12,
    "description": "Plus plan, monthly",
    "return_url": "https://shop.example.com/thanks",
    "metadata": { "plan": "plus", "customer_id": "17" }
  }'
FieldRequiredMeaning
amountyesThe amount of each charge, a decimal string in major units.
currencyyesEUR.
intervalyesTime between charges, see below.
timesnoHow many recurring charges follow the first payment, 1 to 1000. Leave it out to charge until canceled.
descriptionyesShown on the charges, 1 to 255 characters.
return_urlyesWhere the buyer goes after the first payment. An https URL of at most 2048 characters.
metadatanoUp to 20 string keys, copied to the subscription and its payments.

The answer is 201 with the subscription and its first_payment, a full payment object. Creating takes an Idempotency-Key, as for payments.

Response 201 (first_payment shortened)JSON
{
  "id": "sub_0123456789abcdefghjkmnpq",
  "object": "subscription",
  "status": "pending_mandate",
  "amount": "49.00",
  "currency": "EUR",
  "interval": "1 month",
  "times": 12,
  "description": "Plus plan, monthly",
  "metadata": {
    "plan": "plus",
    "customer_id": "17"
  },
  "livemode": true,
  "first_payment_id": "pay_7777777777abcdefghjkmnpq",
  "next_charge_date": null,
  "created": "2026-11-18T10:00:00.000Z",
  "activated_at": null,
  "canceled_at": null,
  "first_payment": {
    "id": "pay_7777777777abcdefghjkmnpq",
    "object": "payment",
    "status": "created",
    "amount": "49.00",
    "currency": "EUR",
    "checkout_url": "https://payments.example.com/pay/Lm4Rt8ZkQw2VxYb6HnJcPdSaEfGiU0KoXtNq3BvM9yD",
    "subscription_id": "sub_0123456789abcdefghjkmnpq"
  }
}

Interval and times

interval is <n> days, <n> weeks or <n> months, with n from 1 to 999 and no leading zero, for example "1 month", "2 weeks" or "14 days". The longest interval is 365 days, 52 weeks or 12 months.

The first recurring charge is one interval after the first payment was paid: paid on 18 November with "1 month", charged on 18 December (UTC). next_charge_date is that day, or null while the subscription is not active.

times does not count the first payment: with times: 12 and a monthly interval, the buyer pays the first payment and then 12 monthly charges.

Collect the first payment

  • Hosted checkout: send the buyer to first_payment.checkout_url.
  • Your own picker: list the methods and select one with the direct payment API. A listed method that cannot give a mandate is refused with 422 method_unavailable: offer another one.

Statuses

StatusMeaningEvent when it is reached
pending_mandateWaiting for the buyer to pay the first payment.–
activeCharged every interval.subscription.activated
canceledStopped by your cancel call, by canceling its first payment, or at the provider. Final.subscription.canceled
completedAll times charges were made. Final.subscription.completed
abandonedThe first payment ended unpaid, or was paid after its window. No charges. Final.subscription.abandoned

Recurring charges

  • Each charge is a payment you can read with GET /v1/payments/{id}. Its subscription_id is the subscription’s id; for a one-off payment it is null.
  • Its description and metadata are the subscription’s. There is nothing for the buyer to pay: do not send the buyer to a recurring charge’s checkout_url.
  • You get payment.paid or payment.failed for it. A failed charge does not cancel the subscription; whether the provider retries it is up to the provider.
  • A charge can appear a little after the interval: do not expect it at the exact time.

Read and cancel

Retrieve and cancel a subscriptioncurl
curl -sS https://payments.example.com/api/v1/subscriptions/sub_0123456789abcdefghjkmnpq \
  -H "Authorization: Bearer cp_live_..."

curl -sS -X POST https://payments.example.com/api/v1/subscriptions/sub_0123456789abcdefghjkmnpq/cancel \
  -H "Authorization: Bearer cp_live_..."
  • GET /v1/subscriptions lists the subscriptions of your mode, newest first, with pagination.
  • Cancel takes no body. An active subscription is canceled at the provider first, so no further charge is made. A pending_mandate one has its first payment canceled.
  • A subscription in a final status answers 409 not_cancellable. A provider that cannot be reached answers 502 provider_error with Retry-After: nothing changed, and the call is safe to repeat.