Create a Price with usage_type set to 'metered' and the billing scheme matching your pricing model (per_unit or tiered).
Report usage events to the Stripe Billing meter or the legacy subscription item usage records endpoint as they occur; use the idempotency key field on each usage record to prevent double-counting on retries.
At the end of the billing period, Stripe automatically sums the usage records associated with the subscription item and generates the invoice line item.
Query the usage record summary endpoint during the billing period to verify the accumulated quantity matches your internal usage tracking system.
If a discrepancy is found, identify whether the gap is from missed API calls, retry duplicates, or clock skew; correct by adding an adjustment usage record before the period closes.
Set up an alert when the metered quantity crosses a threshold you configure so you can notify customers before they incur unexpectedly large bills.
Known gotchas
Usage records are immutable once the billing period closes and Stripe generates the invoice; disputes over metered billing must be handled via credit notes or manual adjustments, not by modifying usage records.
The 'sum' aggregation mode adds all reported quantities; the 'last_during_period' and 'max' modes behave differently — verify the aggregation_type on your Price matches your billing intent.
High-volume usage reporting can hit Stripe API rate limits; batch usage events and report them in aggregate rather than one API call per event when your event rate is high.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp