Stripe meter event identifier mapping: customer id vs subscription item id

TL;DR

Stripe meter events must carry an identifier that resolves to the right customer and subscription item; sending the customer id when the meter expects the subscription item id (or vice versa) orphans the usage. Check the meter's customermapping setting: eventpayload uses a field from your event, stripecustomerid uses the Stripe customer directly. Align your event payload with that mapping, backfill any orphaned events, and add a validation step that rejects events whose identifiers resolve to nothing before they enter your pipeline.

The query

Stripe meter event identifier mapping: customer id vs subscription item id

Use this when

• Metered usage not appearing on the invoice
• Meter events rejected or unattributed in Stripe
• Choosing the identifier for usage events

Not for

• Tier or price setup (separate configuration)
• Real-time usage dashboards (use your own store, not Stripe as source of truth)

Steps

1. Open the meter and read its customer_mapping configuration.

Expected output: You know whether it expects a payload field or a Stripe customer id.

1. Inspect a recent event payload and confirm the identifier field is present and correct.

Expected output: You see the mismatch: wrong field, wrong id format, or missing value.

1. Fix the emitter to send the mapped identifier on every event.

Expected output: New events resolve to the right customer and item.

1. Query for events in the gap window and re-send the orphaned usage.

Expected output: The billing period is made whole.

1. Add a pre-send check that resolves the identifier before emitting.

Expected output: Bad identifiers fail fast at the source, not at invoice time.

Variant phrasings

Stripe meter events identifier mapping

usage events not attributed Stripe meter

Stripe customermapping eventpayload vs stripecustomerid

Root cause

The mapping exists because usage events originate in your systems with your ids, while billing lives in Stripe's id space; the meter is the translation layer. A mismatch orphans events silently because Stripe cannot guess which customer your internal id means.

Edge cases

• Subscription item ids change when items are swapped; re-resolve after plan changes
• Duplicate event ids are deduplicated by Stripe; reuse ids only for true retries

Provenance

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