Subscriptions

A subscription puts a customer on one or more plans and bills them every period.

Create a subscription

curl https://bouclay.com/api/v1/subscriptions \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: subscribe-user-42-pro" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "ctm_…",
    "collectionMode": "automatic",
    "items": [{ "priceId": "price_…" }]
  }'

items lists the base plan first, then any add-on plans. Name each with a priceId, or with a planId and the billingInterval you want. For a plan with seats, pass quantity (or quantities by charge code with planId, such as {"seats": 10}).

How you get paid: collection modes

`collectionMode`	How it collects	How it starts
`automatic`	Charges the customer’s saved card.	With something due today, it opens `incomplete` and starts on its first payment. With a trial, it starts `trialing`.
`manual`	Sends each invoice to pay by bank transfer or on its hosted page.	Starts `active` at once, on its payment terms. See Selling to businesses.

An automatic subscription charges the card given as paymentMethod, or the customer’s default card when it has none of its own.

Statuses

Status	Means	Grants access
`incomplete`	The first payment hasn’t gone through yet.	No
`incomplete_expired`	The first payment never went through, so it never started. Final.	No
`trialing`	On a free trial. Nothing has been charged.	Yes
`active`	Billing on schedule.	Yes
`past_due`	A payment failed and Bouclay is retrying.	Yes
`paused`	Billing is paused. `pauseReason` says why.	No
`canceled`	Ended. Final.	No

Every change of status sends subscription.updated. “Grants access” is what entitlements use.

When the first payment fails

The subscription stays incomplete, and the customer can pay the first invoice on its hostedUrl. You can also retry the charge with POST /subscriptions/{id}/retry-payment, which uses the card the subscription would charge now, so a customer who just saved a new card can start without the hosted page. If it is still unpaid after the grace period in Billing settings → Failed payments (7 days unless you change it), it becomes incomplete_expired.

Trials

A trial comes from the price (trialLength and trialUnit, see Catalog). The subscription starts trialing and nothing is charged. When the trial ends, Bouclay charges the subscription’s card, or the customer’s default card. When there is no card, trialEndBehavior decides:

`trialEndBehavior`	When the trial ends with no card
`create_invoice` (default)	Issues the first invoice as usual. The customer pays it on its hosted page or by saving a card.
`pause`	Pauses the subscription.
`cancel`	Cancels the subscription.

To collect a card during the trial, use a checkout session. Bouclay emails the customer before the trial ends.

See the next invoice

GET /subscriptions/{id}/upcoming-invoice estimates the next invoice: fees billed up front for the next period, plus usage so far for this one. On a trial, it is the invoice the trial converts to. With a cancellation scheduled, it is the final invoice. Show it on your billing page so there are no surprises.

Pause and resume

curl https://bouclay.com/api/v1/subscriptions/sub_…/pause \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: pause-sub-123-1" \
  -H "Content-Type: application/json" \
  -d '{"mode": "period_end", "resumesAt": "2026-12-01T00:00:00Z"}'

mode: now (the default) pauses at once. The paid days left are held back, so resuming moves the next renewal out by however long the pause lasted. Paused on 10 February in a month paid to 28 February and back on 20 March, the 18 paid days run from 20 March and the next renewal is 7 April.
mode: period_end pauses from the next renewal, so the customer keeps the time they paid for. The pause shows in scheduledChanges until it starts. When it resumes, a fresh period starts that day.
resumesAt resumes it on its own on that date. Without it, it stays paused until you call POST /subscriptions/{id}/resume.

A paused subscription bills nothing and grants no entitlements. Usage sent for the paused time is refused.

Why a subscription is paused

`pauseReason`	Means	How it comes back
`requested`	You or the customer paused it.	`POST /subscriptions/{id}/resume`.
`payment_overdue`	Suspended for an unpaid invoice. See Failed payments.	Paying the invoice lifts it on its own. Resume is refused with `409 subscription_suspended` while it is unpaid.
`plan_retired`	Its plan was retired with nowhere to move it.	Move it to another plan, then resume.

Cancel

curl https://bouclay.com/api/v1/subscriptions/sub_…/cancel \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: cancel-sub-123-1" \
  -H "Content-Type: application/json" \
  -d '{"mode": "period_end"}'

mode: period_end keeps the subscription running until the end of the period the customer paid for, then ends it. Until then, undo it with POST /subscriptions/{id}/undo-cancel.
mode: immediately ends it now. A usage subscription’s final invoice bills the usage so far.

A canceled subscription can’t be brought back: start a new one. Record why with reason (one of your cancellation reasons, crsn_…) and comment (the customer’s own words).

Changing what a customer pays for

Seats, upgrades, downgrades and moving to another plan are covered in Changing subscriptions.

Get started

Connect your app

Gateways

Catalog and subscriptions

Usage billing

Invoices and payments

Credits

Reporting

Create a subscription

How you get paid: collection modes

Statuses

When the first payment fails

Trials

See the next invoice

Pause and resume

Why a subscription is paused

Cancel

Changing what a customer pays for

​Create a subscription

​How you get paid: collection modes

​Statuses

​When the first payment fails

​Trials

​See the next invoice

​Pause and resume

​Why a subscription is paused

​Cancel

​Changing what a customer pays for

Create a subscription

How you get paid: collection modes

Statuses

When the first payment fails

Trials

See the next invoice

Pause and resume

Why a subscription is paused

Cancel

Changing what a customer pays for