# Usage-based billing

> Bill subscribers for what they use by attaching metered usage to a subscription plan.

Source: https://help.boltapp.com/products/bolt-subscriptions/usage-based-billing

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 [#how-it-works]

Each billing period follows the same four steps:

1. **Ingest.** Your servers send usage events to the [usage events API](/products/bolt-subscriptions/usage-events) as consumption happens. Each event names an event type, a quantity, and the subscription it belongs to.
2. **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.
3. **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](/products/bolt-subscriptions/set-up-usage-based-plan#choose-a-charge-model).
4. **Invoice.** Bolt adds the rated amount to the plan's base price on the invoice for that period. See [how usage is collected](#how-usage-is-collected).

## Building blocks [#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](/products/bolt-subscriptions/meters). |
| Charge model | How a metered quantity becomes an amount: per-unit, graduated, volume, or capped. See [choose a charge model](/products/bolt-subscriptions/set-up-usage-based-plan#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](/products/bolt-subscriptions/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 [#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.

1. **Signup.** The shopper completes the plan's checkout link. Bolt creates the subscription and opens the first billing period. No usage is charged yet.
2. **During the period.** The merchant's servers [report usage events](/products/bolt-subscriptions/usage-events) as the shopper makes calls. The plan's meter keeps a running total.
3. **Alert.** When the total crosses 10,000 calls, Bolt sends the merchant a `subscription_usage_alert` [webhook](/products/bolt-subscriptions/usage-alerts).
4. **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.
5. **Unpaid period.** On Bolt Cart, a failed charge is retried on your [payment recovery](/products/bolt-subscriptions/set-up-flat-plan#configure-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](/products/bolt-subscriptions/usage-invoicing). 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-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](/products/bolt-subscriptions/set-up-flat-plan#configure-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](/products/bolt-subscriptions/usage-invoicing).

Plans without usage are not affected. They continue to charge the saved payment method at renewal.

## Corrections [#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](/products/bolt-subscriptions/usage-events) lists the validation rules.

## Next steps [#next-steps]

* [Get started](/products/bolt-subscriptions/subscriptions-setup), then [set up a usage-based plan](/products/bolt-subscriptions/set-up-usage-based-plan): dashboard steps and the event feed.
* [Report usage events](/products/bolt-subscriptions/usage-events): the API your servers call.
* [Invoicing for usage-based plans](/products/bolt-subscriptions/usage-invoicing): invoice lifecycle, due dates, and unpaid invoices.
* [Usage alerts](/products/bolt-subscriptions/usage-alerts): thresholds, caps, and the webhook.
