Record usage for billing using the API

To report usage data to Stripe, create meter events that include a customer_id, 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:

curl https://api.stripe.com/v1/billing/meter_events \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d event_name=alpaca_ai_tokens \
  -d "payload[value]"=25 \
  -d "payload[stripe_customer_id]"={{CUSTOMER_ID}}

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.

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.

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.