Set up usage-based alertsPublic preview

Set up alerts to get notified when customers exceed meter usage thresholds, or to trigger an invoice when customers reach a specific billing threshold. You can create alerts that apply to either specific customers or all customers.

Before you begin

You must create a meter before you create an alert.

Create usage alerts

You can configure alerts using the Stripe Dashboard or API.

For example, you can create a one-time alert for customers that triggers when they reach 100 API calls. When a customer reaches 100 API calls, you receive a webhook notifying you that the customer has exceeded the threshold.

Stripe provides a usage alert type called One-time per-customer usage alert. This alert triggers when a customer exceeds the specified usage level for the first time, and only triggers one time per customer, regardless of future usage.

Listen for webhooks

After you configure an alert and start sending usage for that meter, you can listen for webhooks. These events trigger when there’s a status change in Stripe, such as creating a new subscription or invoice.

In your application, set up an HTTP handler to accept a POST request containing the webhook event, and verify the signature of the event.

# 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 '/webhook' do
# You can use webhooks to receive information about asynchronous payment events.
# For more information, see https://stripe.com/docs/webhooks.
webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
payload = request.body.read
if !webhook_secret.empty?

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:

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

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

Limitations

Consider the following limitations for usage alerts:

• Alerts are only evaluated on usage data reported after alert creation.
• You can create a maximum of 25 alerts for each combination of 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.

Consider the following limitations for billing thresholds:

• Thresholds don’t apply to trial subscriptions.
• Billing thresholds aren’t evaluated in the 24 hours before a subscription ends. This helps limit confusion for a customer who receives multiple invoices on the same date.
• Monetary thresholds must be greater than the sum of any flat fees on metered subscription items.
• When determining if a monetary threshold has been reached, the value used excludes taxes but includes discounts and billing credits.
• Subscriptions are only allowed a single monetary threshold.
• Subscription items are only allowed a single usage threshold.
• Invoiced amounts or usage might be slightly higher than the specified thresholds because invoices aren’t issued at the exact moment a specified threshold is reached.
• Per-package tiered pricing isn’t currently supported.