Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
Customers
Products and Prices
Tax Rates
Customer portal
Quotes
Start with a use case
Subscriptions with Checkout
Fixed-price subscriptions with Elements
Metered billing with Elements
Per-seat billing with Elements
Manage subscriptions
How subscriptions work
Subscription webhooks
Change subscriptions
Strong Customer Authentication (SCA)
Improved tax support
Invoices API updates
Migrating to Prices
Additional features
Adding taxes
Applying discounts
Backdating subscriptions
Decimal amounts
Metered billing
Billing thresholds
Multiple subscriptions
Prorations
Setting quantities
Subscriptions with Connect
Subscriptions with multiple products
Subscription schedules
Tiered pricing
Quantity transformation
Using trial periods
Testing
Add payment methods
Bacs Direct Debit in the UK
BECS Direct Debit in Australia
SEPA Direct Debit in the EU
Invoice customers
How invoices work
Create an invoice
Customize invoices
Hosted invoice page
Additional features
Revenue recognition
Overview
Reports
Methodology
Examples
Overrides
Testing
billing
·
HomePaymentsSubscriptionsAdditional features

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=1615111320 \ -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.

Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.
On this page
Creating a metered billing subscription
Reporting usage
Retrieving current usage