Skip to main content
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

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

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 before each request. It is refused with 409 spending_cap_reached once the usage would go past a cap that stops billing.