Record usage for billing using the API
Learn how to record and report usage for your customers.
To report usage data to Stripe, create meter events that include a customer_
, a numerical value, and, optionally, a timestamp. The frequency at which you submit usage data is flexible; you can report it as it occurs or in batches (for example, every day). Stripe automatically calculates the total price at the end of the billing period and provides invoices for all recorded usage during that time.
To create Meter Events:
Idempotency
Use idempotency keys to prevent reporting usage more than one time due to latency or other issues. Every meter event corresponds to an identifier that you can specify in your request (if you don’t specify it, we autogenerate one).
Event timestamps
Make sure that the timestamp falls within the past 35 calendar days and isn’t more than 5 minutes in the future (the 5-minute window accounts for clock drift between your server and Stripe’s systems).
Usage values
The numerical usage value in the payload only accepts positive whole number values.
Interested in using decimal or negative values?
Contact us at usage-based-billing@stripe.com so we can understand your use case better.
Rate limits
Be mindful of the rate limit. The Meter Events endpoint only allows 1000 calls per second per non-Connect Stripe account in live mode, and one concurrent call per customer per meter. If your service might exceed this limit, you can “bundle” your product into amounts. For example, if you charge per 1000 requests, base your product on “per 1k transactions” and send 1 usage record every 1000 times.
Monitor for 429
status codes and implement a retry mechanism with an exponential backoff schedule to manage request volume.
Also, consider incorporating some randomness into the backoff schedule to avoid a thundering herd effect.
Note
If you’re a Connect platform that is making requests on behalf of a connected account using the Stripe-Account
header, you’re subject to regular Stripe rate limits, which is 100 operations per second.
Best practices
Usage data is crucial for accurate user billing. Make your system resilient to network failures. For example, use a reliable queue such as Amazon SQS to push data to Stripe so you can retry if necessary.