Usage-based billing
Bill subscribers for what they use by attaching metered usage to a subscription plan.
Usage-based billing charges a subscriber for measured consumption, in addition to or instead of a fixed recurring price. Your systems report usage events to Bolt. Bolt aggregates them into billable quantities, prices them, and adds the result to the subscriber's invoice for the period.
How it works
Each billing period follows the same four steps:
- Ingest. Your servers send usage events to the usage events API as consumption happens. Each event names an event type, a quantity, and the subscription it belongs to.
- Meter. A meter aggregates the events of one event type into a running total for the period, by summing quantities (
sum) or counting events (count). A meter can filter events by their properties, so one event stream can feed several meters. - Rate. At period end, a charge model converts the metered total into an amount. Bolt supports per-unit, graduated, volume, and capped charge models. See choose a charge model.
- Invoice. Bolt adds the rated amount to the plan's base price on the invoice for that period. See how usage is collected.
Building blocks
| Concept | What it defines |
|---|---|
| Event type | The kind of consumption being reported, for example API calls or storage changes. Event types are registered with Bolt and validate incoming events. |
| Meter | How events of one event type aggregate into a billable quantity: sum or count, with an optional property filter. Meters are reusable across plans. See meters. |
| Charge model | How a metered quantity becomes an amount: per-unit, graduated, volume, or capped. See choose a charge model. |
| Usage alert | A threshold on a meter that notifies you, and optionally the subscriber, as consumption approaches a limit. See usage alerts. |
You attach a meter and a charge model to a plan when you create it. A plan can carry usage configuration alongside a fixed base price.
Example
A merchant sells an API plan at $5.00 per month plus $0.02 per API call, with a usage alert at 10,000 calls.
- Signup. The shopper completes the plan's checkout link. Bolt creates the subscription and opens the first billing period. No usage is charged yet.
- During the period. The merchant's servers report usage events as the shopper makes calls. The plan's meter keeps a running total.
- Alert. When the total crosses 10,000 calls, Bolt sends the merchant a
subscription_usage_alertwebhook. - Renewal. The period closes at 12,400 calls. Bolt rates the usage ($5.00 base + 12,400 × $0.02 = $253.00), bills it, and opens the next period. On Bolt Cart, Bolt charges the saved payment method. On other stores, Bolt issues an invoice and the shopper pays it by its due date.
- Unpaid period. On Bolt Cart, a failed charge is retried on your payment recovery schedule, then the subscription pauses until the shopper pays. On other stores, an invoice past its due date enters dunning and Bolt pauses the next renewal. Either way, no new usage is rated while the subscription is paused, and paying resumes it automatically.
The amount follows measured consumption, the shopper settles an itemized invoice each period, and your integration work is the usage event feed.
How usage is collected
How Bolt collects the period's total depends on your store:
- Bolt Cart. Bolt charges the saved payment method automatically at renewal, the same as a flat plan. A failed charge follows your payment recovery schedule.
- Other stores. A usage-billed plan bills by invoice, unless every charge model on the plan is capped. At each renewal Bolt issues an invoice for the completed period, and the subscriber pays it by its due date. Unpaid invoices pause future renewals. See invoicing for usage-based plans.
Plans without usage are not affected. They continue to charge the saved payment method at renewal.
Corrections
Usage events are immutable once recorded. To correct over-reported usage, issue a credit against the resulting invoice rather than sending a compensating negative event. Counter-style event types reject negative quantities. Only delta-style event types that measure a level, such as storage changes, accept signed quantities. The usage events API lists the validation rules.
Next steps
- Get started, then set up a usage-based plan: dashboard steps and the event feed.
- Report usage events: the API your servers call.
- Invoicing for usage-based plans: invoice lifecycle, due dates, and unpaid invoices.
- Usage alerts: thresholds, caps, and the webhook.