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

Limitations and caveats

• Thresholds do not apply to trialing subscriptions.
• Monetary thresholds must be greater than the sum of all licensed plan costs.
• Billing thresholds are not evaluated during the 24 hours prior to a subscription’s period ending. This helps limit confusion that might arise from a customer’s receiving multiple invoices on the same date.
• Subscriptions are permitted only a single monetary threshold.
• Subscription items are permitted only 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 and/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 plan uses the last_ever aggregation mode, the reset_billing_anchor option cannot be enabled.

Adding a monetary threshold to a subscription

You commonly set an amount threshold’s value to a multiple of the cost of one unit of the product being sold. Setting a lower amount threshold will cause your customers to receive an invoice for every unit of usage, which can lead to customer annoyance or confusion.

The value is a positive integer in the smallest currency unit (e.g., 100 cents to charge $1.00; or 100 to charge ¥100, a zero-decimal currency).

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_4eC39HqLyjWDarjtT1zdp7dc: \
  -d billing_thresholds[amount_gte]=10000 \
  -d billing_thresholds[reset_billing_cycle_anchor]=false

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

Stripe::Subscription.update(
  'sub_49ty4767H20z6a',
  {
    billing_thresholds: {
      amount_gte: 10000,
      reset_billing_cycle_anchor: false,
    },
  }
)

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

stripe.Subscription.modify('sub_49ty4767H20z6a',
  billing_thresholds={
    'amount_gte': 10000,
    'reset_billing_cycle_anchor': False,
  },
)

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

\Stripe\Subscription::update('sub_49ty4767H20z6a', [
    'billing_thresholds' => [
        'amount_gte' => 10000,
        'amount_gte' => false,
    ],
]);

Adding 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 does not currently support setting usage thresholds via the Dashboard.

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

# Set your secret key: remember to change this 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.update('si_CFhSgkWb0MyTWg', {
  billing_thresholds: {
    usage_gte: 2000,
  },
})

# Set your secret key: remember to change this 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.modify('si_CFhSgkWb0MyTWg',
  billing_thresholds={
    'usage_gte': 2000,
  },
)

// Set your secret key: remember to change this 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::update('si_CFhSgkWb0MyTWg', [
    'billing_thresholds' => [
        'usage_gte' => 2000,
    ],
]);

// Set your secret key: remember to change this 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.update('si_CFhSgkWb0MyTWg', {
  billing_thresholds: {
    usage_gte: 2000,
  },
});

Billing cycle anchor

When a customer’s usage reaches a threshold, the subscription’s billing cycle anchor will (by default) not change. For example, if a threshold is reached in the middle of a month-long subscription, the subscription will reset 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 will effectively treat 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_4eC39HqLyjWDarjtT1zdp7dc: \
  -d billing_thresholds[reset_billing_cycle_anchor]=true

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

Stripe::Subscription.update(
  'sub_49ty4767H20z6a',
  {
    billing_thresholds: {
      reset_billing_cycle_anchor: true,
    },
  }
)

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

stripe.Subscription.modify('sub_49ty4767H20z6a',
  billing_thresholds={
    'reset_billing_cycle_anchor': True,
  },
)

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

\Stripe\Subscription::update('sub_49ty4767H20z6a', [
    'billing_thresholds' => [
        'reset_billing_cycle_anchor' => true,
    ],
]);

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

(async () => {
  const subscription = await stripe.subscriptions.update('sub_49ty4767H20z6a', {
    billing_thresholds: {
      reset_billing_cycle_anchor: true,
    },
  });
})();

Note that reset_billing_cycle_anchor=true is not allowed if a metered plan has aggregate_usage=last_ever.

Tiered pricing

Tiers are maintained across threshold invoices. As with a subscription without thresholds, tiers will be reset only at the end of the billing period, or if the subscription has been configured to reset the billing cycle anchor when a threshold is reached.

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.00 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 = $100.00). Once the customer exceeds 10,000 impressions, they are effectively billed every 250 impressions (250 * $0.40 = $100.00). This will continue until the end of the billing period, at which point all un-invoiced usage will be invoiced, and the subscription and tiers will reset.

If you would prefer that tiers reset when a threshold is reached, you must configure the subscription to reset the billing cycle anchor when thresholds are reached.

Volume tiers

Volume tiers define the pricing for all units of usage, as opposed to graduated tiers (used in the example above), 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 (e.g., ad impressions, or GBs of storage).

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

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

Assume that we have a volume tiering plan with the tiers shown in the table below. If a customer uses 10,000 units, the invoice total will be $5,000 (10,000 * $0.50 = $5,000). Any additional usage will cause all usage to be billed at the lower unit cost of $0.40. So, if the customer uses just one more unit, the invoice total drops to $4,000.40 (10,001 * $0.40 = $4,000.40).

If the subscription did not have thresholds, Stripe would issue an invoice for $4,000.40 at the end of the billing period. However, to see how negative invoicing can happen, let’s assume we have a $5,000 monetary threshold. 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 (10,001 * $0.40 = $4,000.40). However, if the customer consumes no more units, then the customer is owed $999.60 ($5,000 - $4,000.40 = $999.60). At the end of the billing period, Stripe will credit this amount to the customer’s balance, which will be used to pay down future invoices.

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

Stripe will not issue an invoice until either the total usage reaches 25,000 units (for a total cost of $10,000), 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