Create a Meter object: POST /v1/billing/meters with 'display_name', 'event_name' (e.g. 'api_calls'), and 'default_aggregation.formula' set to 'sum' or 'count' — this defines how raw events are rolled up each billing period.
Create a Price with 'billing_scheme=per_unit', 'usage_type=metered', and 'recurring.meter={meter_id}' pointing at the meter; set 'unit_amount' or a tiered pricing structure.
Create or update a Subscription with the metered Price; Stripe will not charge at subscription creation because no usage has been reported yet.
Report usage by posting meter events: POST /v1/billing/meter_events with 'event_name' matching the meter, 'payload.stripe_customer_id' (or your identifier field), and 'payload.value' as a string integer; include 'identifier' for idempotency.
At the end of the billing period Stripe automatically aggregates meter events, calculates the charge, and generates the invoice — no explicit finalization call is needed.
To debug, call GET /v1/billing/meters/{id}/event_summaries?customer={customer_id}&start_time=...&end_time=... to see aggregated usage Stripe will bill.
Known gotchas
Meter events are immutable and cannot be deleted — if you accidentally report inflated usage, you must create a corrective negative event or credit the customer manually.
There is an event ingestion delay of up to a few minutes; querying event_summaries immediately after posting an event may not reflect the latest data.
The older 'usage_records' API (SubscriptionItem-level reporting) is a separate system from Billing Meters; mixing both on the same subscription item is not supported — choose one model per price.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?