> ## 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.

# Minimums and spending caps

> Hold a customer to a minimum spend, or cap what they can be billed

> [!NOTE]
>
> Early access, with metered billing.

Two settings on a subscription shape what each billing period costs, whatever the usage:

* A **minimum commitment**: "₦100,000 a month, or your usage, whichever is higher."
* A **spending cap**: "never more than ₦500,000 a month."

Both are measured the same way: what the period bills after discounts and before tax. Set them with `minimumCommitment` and `spendingCap` on `POST /subscriptions`, and change or remove them with `PATCH /subscriptions/{id}` (send `null` to remove). Each change sends `subscription.updated`.

## Minimum commitments

```bash theme={null}
curl -X PATCH https://bouclay.com/api/v1/subscriptions/sub_… \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: min-sub-123-100k" \
  -H "Content-Type: application/json" \
  -d '{"minimumCommitment": 100000}'
```

Fees, usage and prorations count toward the minimum. Credit the customer spends still counts, because credit is a way of paying, not less usage.

When a period bills less than the minimum, the invoice that closes it adds a `minimum` line for the difference: "Minimum commitment · NGN 100,000.00 minimum, NGN 62,000.00 billed". That is the renewal invoice, or the final invoice when the subscription is cancelled. The line takes no discount and is taxed like what it tops up.

* **Trials** owe nothing.
* **Short periods** (cut short by a cancellation, or paused for part of the time) owe their share of the minimum, by time.
* **Changes** apply from now. A period held to ₦100,000 for half the month and ₦40,000 for the other half owes ₦70,000.

Every invoice that closes such a period says what it checked, in `minimumCommitment {amount, counted, shortfall}`. `GET /subscriptions/{id}/upcoming-invoice` shows the same for usage so far, so you can show the customer how far they are from their minimum.

## Spending caps

```bash theme={null}
curl -X PATCH https://bouclay.com/api/v1/subscriptions/sub_… \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: cap-sub-123-500k" \
  -H "Content-Type: application/json" \
  -d '{"spendingCap": {"amount": 500000, "covers": "usage", "behavior": "cap", "warnAt": [80, 100]}}'
```

| Field | Means |
| - | - |
| `amount` | The cap, in major units of the subscription's currency. |
| `covers` | `usage` (the default) counts what usage bills; `all` counts everything the subscription bills. |
| `behavior` | `cap` (the default) bills nothing past the cap; `warn` bills in full and only sends warnings. |
| `warnAt` | Up to five warning points, in percent of the cap. |

When a period goes past a cap that stops billing, its invoice gets a negative `maximum` line: "Spending cap · NGN 500,000.00 cap, NGN 600,000.00 used". VAT is charged on the capped amount. Fees billed up front are always billed in full; the cap only takes back what the invoice bills at the end of the period. A cap on everything can't be lower than the minimum commitment.

A cap changed mid-period applies to the whole period. Raise it and the higher cap holds for the whole month; lower it below what was already billed and nothing more is billed (what was billed stays).

### Warnings

At each point in `warnAt`, your app gets a `spend_alert.created` event with the cap, what was spent, and the period. It is sent once per point, period and cap, whichever `behavior` the cap has. Use it to email the customer or warn them in your app.

### Stopping usage at the cap

Bouclay never blocks usage itself. To stop serving a customer at their cap, either:

* Read `spendingCaps` on `GET /customers/{id}/usage` (`amount`, `spent`, `remaining`, `reached`) before costly work, or
* Place a [credit hold](https://docs.bouclay.com/credits/holds.md) before each request. It is refused with `409 spending_cap_reached` once the usage would go past a cap that stops billing.


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