Usage-based billingLegacy

You can use trial periods for subscriptions with usage-based billing. During the trial period, any usage accrued doesn’t count toward the total charged to the customer at the end of the billing cycle. After the trial period ends, usage accrues and is billed at the end of the next billing cycle.

Learn more about trial periods and subscriptions.

Webhooks and trials

Make sure that your integration properly monitors and handles web events related to changes in trial status.

A few days before a trial ends and the subscription moves from trialing to active, you receive a customer.subscription.trial_will_end event. When you receive this event, verify that you have a payment method on the customer so you can bill them. Optionally, notify the customer that they will be charged.

Learn more about subscriptions and webhooks.

With usage-based billing, the price paid by the customer varies based on consumption during the billing period. When changing the billing period results in ending a subscription’s service period early, you charge the customer for the usage accrued during the shortened billing period.

When a subscription is canceled, it can’t be reactivated. Instead, collect updated billing information from your customer, update their default payment method, and create a new subscription with their existing customer record.

When a subscription has been scheduled for cancellation using cancel_at_period_end, you can reactivate it at any point up to the end of the period by updating cancel_at_period_end to false. The final invoice includes any metered usage when the subscription cancels at the end of the billing period.

Prorations

When your customer changes their subscription, there’s often an adjustment to the amount they owe. This adjustment is known as a proration. You can use the create preview invoice endpoint to display the adjusted amount to your customers.

On the frontend, pass the preview invoice details to a backend endpoint.

function createPreviewInvoice(
  customerId,
  subscriptionId,
  newPriceId,
  trialEndDate
) {
  return fetch('/create-preview-invoice', {
    method: 'post',
    headers: {
      'Content-type': 'application/json',
    },
    body: JSON.stringify({
      customerId: customerId,
      subscriptionId: subscriptionId,
      newPriceId: newPriceId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then(invoice => {
      return invoice;
    });
}

On the backend, define the endpoint for your frontend to call. Create a preview invoice and pass in the changes you want to preview. For this example, you need to delete the subscription item for the old price ID, clear the usage, and then add the new price ID. These changes aren’t actually applied, they just define what the preview looks like.

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

post '/create-preview-invoice' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = Stripe::Subscription.retrieve(data['subscriptionId'])

  invoice =
    Stripe::Invoice.create_preview(
      customer: data['customerId'],
      subscription: data['subscriptionId'],
      subscription_details: {
        items: [
          { id: subscription.items.data[0].id, deleted: true, clear_usage: true },
          { price: ENV[data['newPriceId']], deleted: false }
        ]
      }
    )

  invoice.to_json
end

Billing thresholds allow you to issue an invoice, and to (optionally) reset a subscription’s billing cycle anchor, when a customer’s accrued usage in a subscription service period reaches a specified monetary or usage threshold. Consider using billing thresholds if you want to add precautions to limit the amount owed, or to limit the products consumed, between invoices or charges.

Add a monetary threshold to a subscription

You commonly set the amount of a threshold’s value to a multiple of the cost of one unit of the product being sold.

Setting a lower amount threshold causes your customers to receive an invoice for every unit of usage, which can cause confusion.

The value is a positive integer in the smallest currency unit (for example, 100 cents to charge 1 USD; or 100 to charge 100 JPY, a zero-decimal currency). It must be at least 50 currency units.

You can also set monetary thresholds in the Dashboard, when you create or update a subscription.

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "billing_thresholds[amount_gte]"=10000 \
  -d "billing_thresholds[reset_billing_cycle_anchor]"="false"

Add a usage threshold to a subscription item

As with monetary thresholds, usage thresholds should ideally be greater than one unit of usage, to avoid frequent invoicing. Stripe doesn’t currently support setting usage thresholds through the Dashboard.

curl https://api.stripe.com/v1/subscription_items/si_CFhSgkWb0MyTWg \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "billing_thresholds[usage_gte]"=2000

Thresholds and billing cycle anchor

When a customer’s usage reaches a threshold, the subscription’s billing cycle anchor won’t change (by default). For example, if a threshold is reached in the middle of a month-long subscription, the subscription resets at the end of the month like a subscription without thresholds.

You can change this behavior so that reaching a threshold resets the billing cycle anchor. Doing this effectively treats reaching a threshold as if the subscription had reached its natural rollover point at the end of the month.

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "billing_thresholds[reset_billing_cycle_anchor]"="true"

Be aware that reset_billing_cycle_anchor=true isn’t allowed if a metered subscription has aggregate_usage=last_ever.

Thresholds and tiered pricing

Tiers are maintained across threshold invoices. As with a subscription without thresholds, tiers reset only at the end of the billing period, or if you configure the subscription to reset the billing cycle anchor when it reaches a threshold.

For example, let’s say you run an ad platform that has a graduated tiering structure for ad impressions:

Because usage is billed after the fact, you set a threshold of 100 USD as a stopgap for new customers. Under this scheme, your customer is effectively billed every 200 impressions for the first 10,000 impressions (200 * 0.50 USD = 100 USD). When the customer exceeds 10,000 impressions, they’re effectively billed every 250 impressions (250 * 0.40 USD = 100 USD). This continues until the end of the billing period, at which point all un-invoiced usage are invoiced, and the subscription and tiers reset.

If you prefer that tiers reset upon reaching a threshold, you must configure the subscription to reset the billing cycle anchor when usage reaches the thresholds that you set.

Volume tiers

Volume tiers define the pricing for all units of usage, as opposed to graduated tiers, which define pricing for a specific amount of usage. Some pricing models use volume tiers that decrease the unit cost at each successive tier. You can use such models to incentivize customers to use more of a product (for example, ad impressions, or GB of storage).

When combined with thresholds, these pricing models can lead to invoices with line items for negative amounts, under the following conditions:

1. A threshold invoice has already been issued.
2. Subsequent usage bills at a lower unit cost.

For example, with these tiers:

If a customer uses 10,000 units, the invoice total is 5,000 USD (10,000 * 0.50 USD = 5,000 USD). Any additional usage causes all usage to bill at the lower unit cost of 0.40 USD. So, if the customer uses just one more unit, the invoice total drops to 4,000.40 USD (10,001 * 0.40 USD = 4,000.40 USD).

If the subscription didn’t have thresholds, Stripe would issue an invoice for 4,000.40 USD at the end of the billing period.

However, to see how negative invoicing can happen, assume that we have a 5,000 USD monetary threshold in place. In this scenario, Stripe issues an invoice when the customer reaches 10,000 units of usage.

If the customer uses just one more unit, the invoice total drops to 4,000.40 USD (10,001 * 0.40 USD = 4,000.40 USD). However, if the customer consumes no more units, then they’re owed 999.60 USD (5,000 USD - 4,000.40 USD = 999.60 USD). At the end of the billing period, Stripe credits this amount to the customer’s balance, which is used to pay down future invoices.

Let’s say the customer continues to accrue usage. The cost of this usage reaches 5,000 USD again when the customer has used 12,500 units (5,000 USD / 0.40 USD = 12,500). However, the previous payment of 5,000 USD covers all of this usage, so no invoice is issued.

Stripe won’t issue an invoice until either the total usage reaches 25,000 units (for a total cost of 10,000 USD), or the end of the billing period arrives—whichever occurs first. The tables below show the line items you should expect to see for the two invoices issued in the case where usage reaches 25,000 units.

Invoice 1

Invoice 2

Limitations and caveats

• Thresholds don’t apply to trial subscriptions.
• Monetary thresholds must be greater than the sum of any flat rates on usage-based subscription items.
• Billing thresholds aren’t evaluated during the 24 hours leading up to the end of a subscription. This helps limit confusion for a customer who receives multiple invoices on the same date.
• Subscriptions are only allowed a single monetary threshold.
• Subscription items are only allowed a single usage threshold.
• Given the real-time nature of usage reporting, invoices might not be issued at the exact moment a specified threshold is reached. Invoiced amounts or usage might be slightly higher than the specified thresholds.
• The value used to determine whether a monetary threshold has been reached excludes taxes, but includes discounts and applicable prorations.
• If a subscription uses the last_ever aggregation mode, you can’t enable the reset_billing_anchor option.

You can apply the usage-based pricing model in situations where the unit you’re measuring isn’t strictly based on a sum.

For example, Typographic offers a copywriting service where they charge based on how many words are written. Typographic bills their customers at the end of the month based on their usage of the copywriting service, in addition to the flat monthly fee. Typographic wants to charge for the maximum number of words used per customer per month. They can configure this with the aggregate_usage parameter:

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d nickname="Copywriting service" \
  -d product={{PRODUCT_ID}} \
  -d unit_amount=10000 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d "recurring[usage_type]"=metered \
  -d "recurring[aggregate_usage]"=max

Imagine that a customer has 2,000 words written on June 1, then has another 1,000 words written on June 15. Later, they’re credited for 1,000 of the first 2,000 words on June 20. The billed amount at the end of the month is 2.00 USD (2,000 words maximum usage during the month, charging .10 USD per word).

The aggregate_usage parameter determines how subscriptions handle usage records. Here are the options for that parameter:

• sum—The default value (passed if you don’t specify the parameter). 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 recently provided usage record. 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.

curl https://api.stripe.com/v1/prices \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -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.

Use the transform_quantity option to aggregate usage before multiplying by unit cost. This is useful if you want to report a different quantity or usage before totaling price.

Typographic decides to expand their offerings with a custom font design service. Custom designs can be labor-intensive, so they charge an extra fee (another Product) based on the level of customization. Designers report the exact length of time it took to perform the customization, but Typographic doesn’t want to charge customers by the minute. Instead, Typographic charges for each hour spent customizing-even a partial hour.

First, create the font customization product:

curl https://api.stripe.com/v1/products \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Font Customization Service" \
  -d unit_label=Hours

Next, create a price for the font customization service product, charging 150 USD an hour and rounding up (to charge for a full hour even if only part of the hour is used):

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d nickname="Customization Per Hour Rate" \
  -d unit_amount=15000 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d "recurring[usage_type]"=metered \
  -d product={{FONT_CUSTOMIZATION_SERVICE_PRODUCT_ID}} \
  -d "transform_quantity[divide_by]"=60 \
  -d "transform_quantity[round]"=up

If a designer spends 150 minutes customizing, that customer would be charged 450 USD for 3 hours of customization (2 hours and 30 minutes, rounded up).