> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouclay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions

> Start, trial, pause and cancel subscriptions, and what each status means

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

## Create a subscription

```bash theme={null}
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](https://docs.bouclay.com/billing/invoices.md#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](https://docs.bouclay.com/integrate/entitlements.md) 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](https://docs.bouclay.com/billing/catalog.md#free-trials)). 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](https://docs.bouclay.com/integrate/saving-cards-and-portal.md#save-a-card-with-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

```bash theme={null}
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](https://docs.bouclay.com/billing/failed-payments.md). | 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

```bash theme={null}
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](https://docs.bouclay.com/billing/changing-subscriptions.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.