how to report usage to the Stripe meter events API

TL;DR

Create a meter for the event name, then POST meter events with the customer (or subscription item) identifier, timestamp, and value; Stripe aggregates them into the billing period. Send events as they happen, idempotently, with your own event id so retries never double-count. Verify aggregation on the meter dashboard before the first invoice.

Steps

1. Create the meter: event name, aggregation formula (sum, max, last), and customer mapping.

Expected: The meter defines how raw events become a billable number.

1. From your app, POST a meter event per usage occurrence with identifier, timestamp, and value.

Expected: Usage streams into Stripe in near real time.

1. Attach your own idempotency key per event so network retries cannot double-count.

Expected: At-least-once delivery becomes exactly-once billing.

1. Check the meter dashboard: event counts and aggregated values should match your app logs.

Expected: The pipeline is verified before money is involved.

1. Attach the meter to a price on the subscription so the period close bills the aggregate.

Expected: Usage flows into invoices automatically.

When to use

• You bill per API call, seat-hour, or other usage unit
• You need the meter events API specifically (not the older usage records)
• Usage must be idempotent under retries

When not to use

• You debug zero usage on an invoice (different checklist)
• Your usage is tiered per-seat licensing (meters may be overkill)
• You report usage in bulk rarely (batch carefully; late events miss the period)

Compatibility

Stripe Billing Meters API (meter events); replaces legacy usage records. All SDKs.

Variant phrasings

### Stripe meter events API example

### report usage Stripe Billing meter

### meter event idempotency Stripe

Root cause

Meters decouple event ingestion from billing math: your app emits facts (what happened, when), and Stripe applies the aggregation formula at period close. The idempotency requirement exists because usage pipelines retry, and double-counted usage is the fastest way to destroy customer trust in usage billing.

Edge cases

• Events timestamped outside the billing period do not count toward it; clock skew matters
• The event_name must match the meter exactly, including case
• High-volume meters need batching; check rate limits before launch

Provenance

Resolved from the public thread: https://vectle.com/posts/pstKqCccCzjCOWZGwNAEu_8w