Stripe usage-based invoice shows zero usage: debugging missing meter events
Debugs Stripe usage-based invoices that bill zero. Use when a metered subscription invoice shows no usage despite real activity. Not for setting up meters initially.
TL;DR
Zero usage on the invoice means events never reached the meter or never matched it: check the event name and identifier match the meter config, confirm events arrived inside the billing period, and verify the meter is attached to the subscription price. Walk the chain app to meter to invoice; the break is usually a mismatched event name or identifier.
Steps
- In your app logs, confirm usage events were actually emitted for the customer and period.
Expected: You rule out the app never sending.
- Check the meter dashboard for received events in the period; compare counts to your logs.
Expected: You see whether Stripe received them.
- Verify the event_name matches the meter exactly and the identifier maps to the right customer.
Expected: Mismatches found here explain most zeros.
- Confirm event timestamps fall inside the invoice billing period.
Expected: Late or early events explain the rest.
- Confirm the meter is attached to the subscription item price for that customer.
Expected: An unattached meter bills nothing by design.
When to use
- A usage invoice bills zero unexpectedly
- Meter events seem sent but invoice shows nothing
- You need a systematic debug order
When not to use
- Usage is nonzero but wrong (aggregation formula issue)
- You have not built the reporting pipeline yet
- The subscription is trialing (no billing period yet)
Compatibility
Stripe Billing Meters API and dashboard; invoice line inspection. All SDKs.
Variant phrasings
### Stripe metered billing zero usage invoice
### meter events not showing Stripe
### usage based invoice empty Stripe
Root cause
The chain has four links (emit, ingest, match, attach) and a zero means exactly one broke: the meter only aggregates events whose name and identifier match its config inside the period, for a subscription actually linked to it. Debugging in chain order finds the break fast.
Edge cases
- Identifier mapping (customer id vs subscription item id) is the subtlest mismatch
- Test clocks create periods in the past; events timestamped now miss them
- Aggregation last-ever with no events yields zero, not an error
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_kNWMyaGdNHwhBlYDnSHinA
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.