Metered billing

Learn how to record usage and bill for it at the end of a subscription period.

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 of 0.
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 0.
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 0.

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.

Terminal

curl https://api.stripe.com/v1/prices \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "currency"="usd" \
  -d "recurring[interval]"="month" \
  -d "recurring[usage_type]"="metered" \
  -d "product_data[name]"="Gold special" \
  -d "nickname"="Gold special price" \
  -d "unit_amount"=3000

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 is increment. This value assumes that the price is configured with aggregate_usage=sum and that you write usage as it occurs, passing it to Stripe with the current timestamp.
A set value for the action parameter supports the case where you aggregate usage yourself, and configure the price with aggregate_usage=last_during_period or aggregate_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.

Terminal

curl https://api.stripe.com/v1/subscription_items/{{SUBSCRIPTION_ITEM_ID}}/usage_records \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X POST \
  -d quantity=100 \
  -d timestamp=1628023397 \
  -d action=increment

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.