Alerts and thresholdsBeta

Alert when a customer exceeds a usage threshold or trigger an invoice when a customer hits a billing threshold.

Usage Alerts

You can set up usage alerts on meter usage. You can configure alerts to trigger a webhook when customers reach specific usage levels. Alerts apply to specific customers or all customers. Usage alert types:

One-time per-customer usage alert: Triggers when a customer exceeds a specified usage level for the first time. As an example, you create a one-time alert for customers when they reach 100 API calls. When any customer reaches 100 API calls, you receive a webhook notifying you that the customer has exceeded the threshold. This alert only triggers once per customer, regardless of future usage.

You can use usage alerts in your business workflows, such as the following:

Email Users: Allow users to configure usage limits, and send an email when they hit their limit.
De-provision Access: Give users a free number of usage units to your service and remove access when they exceed a limit.
Notify the sales team of an upsell: Alert your sales team of an enterprise opportunity when a self-serve user exceeds a usage threshold.

Alerts can be created using Dashboard or the API.

To setup an alert:

Navigate to the Billing Alerts page.
Click Create Alert.
Name the alert and specify the meter you want to alert for.
Set the unit threshold.
(Optional) Specify a customer filter that you want that alert to run for, otherwise the alert will be configured for all customers.
Click Save.

After you’ve configured an alert and started sending usage for that meter, you then need to listen for webhooks.

Limitations

Alerts aren’t evaluated on alert creation and are only evaluated on usage data reported after alert creation.
There’s a limit of 25 alerts at every scope (that is, a combination of meter and customer filter). For example, you can’t create more than 25 alerts for a specific meter and customer. However, you can create an alert for a specific meter for each of your customers.
Alerts currently don’t work with test clocks.

Spend and credit alerts

You can specify alerts for when customers exceed a certain amount of spend or their available credits get low. When customers meet these thresholds are met, the alert triggers a webhook. Click here if you’re interested in joining the beta.

Billing thresholds

You can create billing thresholds to issue an invoice and to optionally reset a subscription’s billing cycle anchor after a customer’s accrued usage in a subscription cycle reaches a specified monetary threshold. Consider using billing thresholds 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

It’s common to set the value of a threshold as 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 might 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). Set the value to at least 50 currency units.

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

Add a usage threshold to a subscription item

Set usage thresholds to exceed one unit of usage to prevent frequent invoicing. Stripe doesn’t support setting usage thresholds in the Dashboard.

Thresholds and billing cycle anchor

By default, the billing cycle anchor of a subscription remains unchanged after a customer’s usage reaches a threshold. For example, if a threshold is reached in the middle of a month-long subscription, the subscription resets at the end of the month, similar to a subscription without thresholds.

You can change this behavior by configuring the subscription to reset the billing cycle anchor after it reaches a threshold. Stripe treats the reaching of a threshold as if the subscription had naturally arrived at its rollover point at the end of the month.

Thresholds and tiered pricing

Stripe maintains tiers across threshold invoices. Tiers reset at the end of the billing period by default, or if you configure the subscription to reset the billing cycle anchor after it reaches a threshold, similar to a subscription without thresholds.

Say you run an ad platform that has the following graduated tiering structure for ad impressions:

Tier	Amount (unit cost)
1-10000 (`up_to=10000`)	0.50 USD (`unit_amount=50`)
10000+ (`up_to=inf`)	0.40 USD (`unit_amount=40`)

Because Stripe bills usage retrospectively, you can set a threshold of 100 USD as a temporary measure for new customers. Under this plan, your customer is billed every 200 impressions for the first 10,000 impressions (200 x 0.50 USD = 100 USD). When the customer exceeds 10,000 impressions, they’re billed every 250 impressions (250 x 0.40 USD = 100 USD). This continues until the end of the billing period, at which point all of the un-invoiced usage is invoiced, and the subscription and tiers reset.

To enable the resetting of tiers after reaching a threshold, you must configure the subscription to reset the billing cycle anchor after the 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 these 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:

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

For example, consider the following tiered pricing structure:

Tier	Amount (unit cost)
1-10000 (`up_to=10000`)	0.50 USD (`unit_amount=50`)
10000+ (`up_to=inf`)	0.40 USD (`unit_amount=40`)

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

Without 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 occur, 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 one more unit, the invoice total drops to 4,000.40 USD (10,001 x 0.40 USD = 4,000.40 USD). However, if the customer doesn’t consume more units, 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 we use to pay down future invoices.

Say the customer continues to accrue usage. The cost of this usage reaches 5,000 USD again when the customer uses 12,500 units (5,000 USD / 0.40 USD = 12,500). However, the previous payment of 5,000 USD covers all of this usage. As a result, we don’t issue an invoice.

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 see for the two invoices issued in the scenario where usage reaches 25,000 units.

Invoice 1:

Line item	Quantity	Amount
Usage (0.50 USD per unit)	10,000	5,000 USD
Total		5,000 USD

Invoice 2:

Line item	Quantity	Amount
Usage (0.40 USD per unit)	25,000	10,000 USD
Amount previously billed (at 0.50 USD per unit)		-5,000 USD
Total		5,000 USD

Limitations

Thresholds don’t apply to trial subscriptions.
Monetary thresholds must be greater than the sum of any flat fees on metered 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.
We only allow subscriptions a single monetary threshold.
We only allow subscription items a single usage threshold.
Because of the real-time nature of usage reporting, we might not issue invoices 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.
Per-package tiered pricing isn’t currently supported.

Listen for webhooks

To complete the integration, you need to process webhooks sent by Stripe. These events are triggered whenever there’s a change in the state within Stripe, such as the creation of new subscriptions and invoices. In your application, set up an HTTP handler to accept a POST request containing the webhook event, and verify the signature of the event:

During development, use the Stripe CLI to monitor webhooks and forward them to your application. Run the following in a new terminal while your development app is running:

Command Line
stripe listen --forward-to localhost:4242/webhook

For production, set up a webhook endpoint URL in the Dashboard, or use the Webhook Endpoints API.