Billing
Start with a use case
Manage subscriptions
Add payment methods
Invoice customers
Revenue recognition
Sign in
Sign up
Support
Sign in
Billing
Additional features
Metered billing
HomePaymentsBillingAdditional features

Metered billing

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

Metered billing is useful in cases where you want to charge your customers a granular amount based on their consumption of your service during the billing cycle, instead of explicitly setting quantities. For example, if you are running an email SaaS business, you can track your customers’ API calls, then bill them for the total number used at the end of each month.

Creating a metered billing subscription

To use metered billing, create a new price, configure it with metered as the recurring[usage_type], and attach it to an existing product. Specify the desired amount, interval, and currency. With a metered price, the amount is billed per unit of consumption. Note that we also support tiered pricing, which means we can dynamically adjust the price per unit depending on the total amount of units sold within a period.

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

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

price = Stripe::Price.create({
  currency: 'usd',
  recurring: {
    interval: 'month',
    usage_type: 'metered',
  },
  product_data: {
    name: 'Gold special',
  },
  nickname: 'Gold special price',
  unit_amount: 3000,
})

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

price = stripe.Price.create(
  currency='usd',
  recurring={
    'interval': 'month',
    'usage_type': 'metered',
  },
  product_data={
    'name': 'Gold special',
  },
  nickname='Gold special price',
  unit_amount=3000,
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$price = \Stripe\Price::create([
  'currency' => 'usd',
  'recurring' => [
    'interval' => 'month',
    'usage_type' => 'metered',
  ],
  'product_data' => [
    'name' => 'Gold special',
  ],
  'nickname' => 'Gold special price',
  'unit_amount' => 3000,
]);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

PriceCreateParams params =
  PriceCreateParams.builder()
    .setCurrency("usd")
    .setRecurring(
      PriceCreateParams.Recurring.builder()
        .setInterval(PriceCreateParams.Recurring.Interval.MONTH)
        .setUsageType(PriceCreateParams.Recurring.UsageType.METERED)
        .build())
    .setProductData(
      PriceCreateParams.ProductData.builder()
        .setName("Gold special")
        .build())
    .setNickname("Gold special price")
    .setUnitAmount(3000L)
    .build();

Price price = Price.create(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const price = await stripe.prices.create({
  currency: 'usd',
  recurring: {
    interval: 'month',
    usage_type: 'metered'
  },
  product_data: {
    name: 'Gold special',
  },
  nickname: 'Gold special price',
  unit_amount: 3000,
});

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.PriceParams{
  Currency: stripe.String(string(stripe.CurrencyUSD)),
  Recurring: &stripe.PriceRecurringParams{
    Interval:  stripe.String(string(stripe.PriceRecurringIntervalMonth)),
    UsageType: stripe.String(string(stripe.PriceRecurringUsageTypeMetered)),
  },
  ProductData: &stripe.PriceProductDataParams{
    Name: stripe.String("Gold special"),
  },
  Nickname:   stripe.String("Gold special price"),
  UnitAmount: stripe.Int64(2000),
}
p, _ := price.New(params)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new PriceCreateOptions
{
  Currency = "usd",
  Recurring = new PriceRecurringOptions
  {
    Interval = "month",
    UsageType = "metered",
  },
  ProductData = new PriceProductDataOptions
  {
    Name = "Gold special",
  },
  Nickname = "Gold special price",
  UnitAmount = 3000,
};

var service = new PriceService();

Price price = service.Create(options);

To subscribe a customer, create or update a subscription via the API endpoint, and do not specify a quantity—metered billing doesn’t use the subscription item quantity attribute. When you create the subscription, Stripe returns the subscription item record, which includes an ID. You should save this ID and associate it with the user, because it is used for usage reporting.

By default, Stripe computes the total usage to be billed at invoice time by summing up all quantity values of subsequent usage records written with a billing period. When creating a price for metered billing, you can use the aggregate_usage parameter to configure alternative behaviors:

  • By setting the parameter to last_during_period, the latest usage record written during a period will determine the quantity for which to invoice. If no usage records are present during the given period, Stripe will invoice for the quantity of 0.
  • By setting the parameter to last_ever, the latest usage record ever written will determine the quantity for which to invoice. This means that even if no usage has been reported within a given period, Stripe will seek further back in time to find a usage record. If no usage records are present at all, Stripe will invoice for the quantity of 0.
  • By setting the parameter to max, the quantity for which to invoice is determined by looking through all usage records reported during a given period, and picking the maximum quantity. If no usage records are present during the given period, Stripe will invoice for the quantity of 0.

Reporting usage

In order for Stripe to compute the number of units at invoice time, you must report the customer’s usage by creating usage records on the subscription item, with the ID that you saved in the previous step.

The Usage API call includes a timestamp, quantity, and action. The increment action adds the quantity to the usage total for the specified timestamp. The set action overwrites the usage for the specified timestamp.

  • If you preaggregate usage yourself, Stripe recommends periodically writing the current value, with the current timestamp and action=set, as the usage record. The underlying price can be configured as aggregate_usage=last_during_period or aggregate_usage=last_ever.
  • If you do not aggregate usage on your end, you can write usage as it occurs, and use action=increment with the current timestamp. The underlying price should be configured as aggregate_usage=sum. Reserve the set action for the unusual case where you need to make a usage adjustment.

Note that reporting usage outside of 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.

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

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::SubscriptionItem.create_usage_record(
  '{{SUBSCRIPTION_ITEM_ID}}',
  {
    quantity: 100,
    timestamp: 1522893428,
    action: 'increment',
  }
)


# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.SubscriptionItem.create_usage_record(
  '{{SUBSCRIPTION_ITEM_ID}}',
  quantity=100,
  timestamp=1522893428,
  action='increment',
)


// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\SubscriptionItem::createUsageRecord(
  '{{SUBSCRIPTION_ITEM_ID}}',
  [
    'quantity' => 100,
    'timestamp' => 1522893428,
    'action' => 'increment',
  ]
);


// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

UsageRecordCreateOnSubscriptionItemParams params =
  UsageRecordCreateOnSubscriptionItemParams.builder()
    .setQuantity(100L)
    .setTimestamp(1522893428L)
    .setAction(UsageRecordCreateOnSubscriptionItemParams.Action.INCREMENT)
    .build();

UsageRecord.createOnSubscriptionItem("{{SUBSCRIPTION_ITEM_ID}}", params);


// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.subscriptionItems.createUsageRecord(
  '{{SUBSCRIPTION_ITEM_ID}}',
  {
    quantity: 100,
    timestamp: 1522893428,
    action: 'increment',
  }
);


// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.UsageRecordParams{
  SubscriptionItem: stripe.String("{{SUBSCRIPTION_ITEM_ID}}"),
  Quantity: stripe.Int64(100),
  Timestamp: stripe.Int64(1522893428),
  Action: stripe.String(string(stripe.UsageRecordActionIncrement)),
}
ur, _ := usagerecord.New(params)


// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new UsageRecordCreateOptions
{
  Quantity = 100,
  Timestamp = DateTimeOffset.FromUnixTimeSeconds(1522893428).UtcDateTime,
  Action = "increment",
};
var service = new UsageRecordService();
var usageRecord = service.Create("{{SUBSCRIPTION_ITEM_ID}}", options);

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