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_idset. 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
- You create the subscription with
POST /v1/subscriptions. It ispending_mandate, and the answer carries its first payment. - The buyer pays the first payment, on its checkout or with a method you select through the direct API.
- When the first payment is paid, the subscription becomes
activeand you getsubscription.activated. - On every interval the buyer is charged. Each charge is a payment with
subscription_idset, reported with the usualpayment.*events. - 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
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" }
}'| Field | Required | Meaning |
|---|---|---|
amount | yes | The amount of each charge, a decimal string in major units. |
currency | yes | EUR. |
interval | yes | Time between charges, see below. |
times | no | How many recurring charges follow the first payment, 1 to 1000. Leave it out to charge until canceled. |
description | yes | Shown on the charges, 1 to 255 characters. |
return_url | yes | Where the buyer goes after the first payment. An https URL of at most 2048 characters. |
metadata | no | Up 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.
{
"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
| Status | Meaning | Event when it is reached |
|---|---|---|
pending_mandate | Waiting for the buyer to pay the first payment. | – |
active | Charged every interval. | subscription.activated |
canceled | Stopped by your cancel call, by canceling its first payment, or at the provider. Final. | subscription.canceled |
completed | All times charges were made. Final. | subscription.completed |
abandoned | The 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}. Itssubscription_idis the subscription’s id; for a one-off payment it isnull. - Its
descriptionandmetadataare the subscription’s. There is nothing for the buyer to pay: do not send the buyer to a recurring charge’scheckout_url. - You get
payment.paidorpayment.failedfor 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
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/subscriptionslists the subscriptions of your mode, newest first, with pagination.- Cancel takes no body. An
activesubscription is canceled at the provider first, so no further charge is made. Apending_mandateone has its first payment canceled. - A subscription in a final status answers
409 not_cancellable. A provider that cannot be reached answers502 provider_errorwithRetry-After: nothing changed, and the call is safe to repeat.