Metered billing
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.
Like other subscription models, metered billing is defined by the prices you create for your product or service. You must also record usage, and you can customize how to handle usage records.
Creating a metered billing subscription
When you create a price for metered billing, you specify:
"recurring[usage_type]"=metered
- 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 of0
.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 of0
.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 of0
.
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
quantity
. - Make sure to record the subscription item ID. You pass this value to the Usage Records API to report usage.
Reporting 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
action
parameter isincrement
. This value assumes that the price is configured withaggregate_usage=sum
and that you write usage as it occurs, passing it to Stripe with the currenttimestamp
.A
set
value for theaction
parameter supports the case where you aggregate usage yourself, and configure the price withaggregate_usage=last_during_period
oraggregate_usage=last_ever
.
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.
Retrieving current usage
To retrieve total usage for the current period, you can retrieve the upcoming invoice for the subscription. The usage is reflected as the quantity
of the invoice item for a subscription_item
.