Early access. Write to hello@bouclay.com to have metered billing turned on for your account.
1
Create a meter
A meter names an event and how to add it up.
2
Put a usage price on it
A price decides what each unit costs. One meter can back many prices.
3
Subscribe the customer
The subscription bills the usage at the end of each period.
4
Send events as they happen
Bouclay counts them and puts the total on the invoice.
1. Create a meter
aggregation decides how a period’s events become one number:
For
sum, max and last, the number comes from the event’s value, or from a property you name with valueKey.
eventName, aggregation, valueKey and uniqueKey can’t change once the meter has events, because that would change what past usage cost. To count differently, create a new meter.
2. Put a usage price on it
A usage price is a recurring price withusageType: metered and the meter’s id:
graduated tiers for included units and volume discounts, or package for blocks. See Pricing models.
Pricing per a number of units
When a unit costs less than a kobo, quote the rate per a number of units withunitDivisor. ₦4,500 per 1,000,000 tokens is "unitAmount": 4500, "unitDivisor": 1000000. Bouclay bills usage × unitAmount ÷ unitDivisor, adds up every tier first, and rounds half up to the kobo once: 2,345,678 tokens bill ₦10,555.55. The invoice line says the rate: “Input tokens · 2,345,678 tokens · NGN 4,500.00 per 1M tokens”.
Fees billed at the end
A fixed fee can also be billed at the end of the period withbillingTiming: arrears, prorated to the time the subscription was live. This is how “pay as you go” plans with no upfront charge are made.
3. Subscribe the customer
Subscribe them as usual. A plan with nothing billed up front has nothing to charge today, so it startsactive. To make sure there is a card for the first invoice, set requirePaymentMethod: true (or turn it on for every subscription in Billing settings → Signups): the customer saves a card through a small refunded charge, and the subscription starts once it settles.
To bill several kinds of usage on one plan, such as a platform fee plus SMS plus lookups, see Sell several kinds of usage in one plan.
4. Send usage events
- No
Idempotency-Keyneeded.identifieris your own unique id for the event. Sending the same one again returns the stored event (200) and counts it once. Send events again freely after a timeout. customeris the Bouclay id or theexternalRefyou gave the customer.valueis forsum,maxandlastmeters. Whole numbers only, so pick a unit that makes it one (tokens, not thousands of tokens; kobo, not naira).timestampdefaults to now and can’t be more than 5 minutes ahead.
POST /meter-events/batch. Each event is judged on its own, so one bad event never fails the batch, and the response gives each one’s outcome: created, duplicate or rejected.
Refused events
A refused event answers422 with a code:
Correcting a mistake
POST /meter-events/{identifier}/cancel stops an event counting. It is kept, never deleted, and its identifier stays used. Events in a period that is already invoiced can’t be cancelled; correct the invoice with a credit note instead.
Show customers their usage
GET /customers/{id}/usage returns each meter’s usage this period, with estimatedAmount: what it would bill now, priced exactly as the invoice line will be. GET /subscriptions/{id}/upcoming-invoice shows the whole next invoice. Both are good for a usage page in your app.
Billing large usage early
A customer can run up a large bill before the period ends.invoicingThreshold on the subscription bills usage early once the unbilled amount reaches it. The period’s own invoice then bills only the rest. Fixed fees never count toward it.
Minimums, caps and credit
- Hold a customer to a minimum spend, or cap what they can be billed: see Minimums and spending caps.
- Let customers pay for usage up front and stop them when it runs out: see Prepaid credit and Credit holds.