The objects
How a subscription bills
1
You build the catalog once
A product holds plans. Each plan holds one or more charges, and each charge has a price per currency and interval. See Catalog.
2
A customer subscribes
A subscription takes every active charge of the plan. A trial starts at once; otherwise the first invoice is issued straight away.
3
Bouclay issues an invoice each period
Fixed fees are billed at the start of the period. Usage is counted from meter events and billed when the period ends.
4
Bouclay collects it
With
collectionMode: automatic, Bouclay charges the customer’s saved card through your gateway. With manual, the customer pays the invoice by bank transfer or on its hosted page.5
If a payment fails, Bouclay retries
The subscription turns
past_due, the customer gets emails, and Bouclay retries on your schedule. See Failed payments.6
Your app hears about every change
Every change fires a webhook. Read the object’s
status and update your app. See Webhooks.Test mode and live mode
Test keys (sk_test_…) charge through your gateway’s test account, and live keys (sk_live_…) through its live account. Saved cards belong to one mode: a test key can never reach a live card. See Going live.
Money is in major units
The API sends and receives amounts in major units:5000 is ₦5,000, not 50 naira. Bouclay keeps exact minor units inside and rounds once, at the end. See Money.
Early access features
Some features are documented before they are turned on for every account: usage billing, tiered pricing, entitlements, discounts, credit holds, metrics, the cancellation flow, plan retirement, routing between gateways, and the Paystack, Flutterwave and Nomba gateways. They carry an Early access badge in the API reference. Until a feature is on for your account, its endpoints answer404 not_found and its fields are refused with a 422. Write to hello@bouclay.com to have one turned on. Nothing you already use changes when it is.