With metered billing, you charge your customers based on their consumption of your service during the billing cycle, instead of explicitly setting quantities. For example, if you run an email SaaS business, you can record how many emails your customers send per month, then bill them for the total number at the end of the month.
Creating a metered billing subscription
When you create a price for metered billing, you specify:
- Interval and currency
- Amount per unit of consumption
You can also specify a value for
aggregate_usage. This parameter determines how usage records are handled.
- The default value (passed if you do not specify the parameter) is
sum. The total billed is based on the sum of all usage records for the billing period.
last_during_period– the total billed is based on the most recent usage record for the billing period. If no usage is reported for the billing period, the total billed is based on a usage quantity of
last_ever– the total billed is based on the most recent usage record ever provided. If no usage is reported during the current billing period, Stripe looks for a previous usage record. If no usage record is found, the total billed is based on a usage quantity of
max– the total billed is based on the usage record with the largest usage quantity for the billing period. If no usage is reported for the billing period, the total billed is based on a usage quantity of
Which option you choose depends on how you handle usage on your end. You also set the value of the
action parameter of the usage records API to reflect how you record usage.
When you create the subscription:
- Don’t pass
- Make sure to record the subscription item ID. You pass this value to the Usage Records API to report usage.
Stripe expects that you maintain your own system for recording customer usage, but you must also provide usage information for subscriptions to Stripe. Note the following:
The default value for the
increment. This value assumes that the price is configured with
aggregate_usage=sumand that you write usage as it occurs, passing it to Stripe with the current
setvalue for the
actionparameter supports the case where you aggregate usage yourself, and configure the price with
Reporting usage outside the current billing interval results in an error. Stripe leaves a five-minute window in the default aggregation mode (
aggregate_usage=sum) after the period ends to allow for clock drift. For all other aggregation modes the
timestamp must be within the current period.
Note: Using an idempotency key lets you safely re-report usage in the event of intermittent API errors.
At the end of a subscription period, Stripe automatically totals and invoices for all usage during the billing period. Metered billing invoices respect trials. Note that once the invoice is submitted, it cannot be changed. The usage reporting endpoint is rate-limited, so you might need to exercise caution and avoid making too many separate usage records.
When canceling a subscription at the end of the period, any usage reported before the subscription ends is billed in a final invoice at the end of the period. Canceling a subscription immediately does not bill for any usage accrued during the final billing cycle.