Mapping Stripe customers to application users without guessing
A billing audit is only as reliable as the link between a Stripe customer and an application account. Email matching is not an identity strategy.
A subscription record does not know who your user is. It knows a Stripe customer ID, a price, a status, and a collection of metadata. Your application knows a user ID and an access state. Somewhere between those two systems, an identity decision has to be made.
When that decision is implicit — “we match on email” — it becomes a permanent source of false positives. People change email. Teams share inboxes. Checkout can create a second customer for the same person. Test records and production records can coexist in the same Stripe account.
Use a durable mapping table
Create a first-class mapping between application users or organizations and Stripe customer IDs. Treat a change of billing account as a new mapping with a validity window, not an overwrite. That preserves the ability to explain historical findings.
- Store the Stripe customer ID, the internal user or organization ID, and the source of the mapping.
- Record created_at, verified_at, and retired_at so historical comparisons remain explainable.
- Allow one organization to map to several Stripe customers if that reflects how it buys.
- Never infer a mapping from a display name.
Set metadata at checkout
When creating a Checkout Session or subscription, attach the authenticated internal identifier in metadata. Do not trust a value supplied directly by the browser; derive it from the server-side session. Then persist the resulting Stripe customer and subscription IDs when the signed webhook is processed.
// Server-side only. workspaceId comes from the authenticated session.
const session = await stripe.checkout.sessions.create({
mode: 'subscription',
customer: existingCustomerId,
client_reference_id: workspaceId,
metadata: { workspace_id: workspaceId },
subscription_data: { metadata: { workspace_id: workspaceId } },
line_items: [{ price, quantity: 1 }],
success_url,
cancel_url,
})Handle the awkward cases explicitly
- One user, multiple customers: keep both mappings active and choose the effective subscription by status and period.
- One customer, multiple users: map at the organization or seat level; do not flag every user as an unlinked duplicate.
- No customer ID: this is an identity gap, not proof of non-payment. Surface it for review separately.
- Deleted Stripe customer: preserve the historical ID and mark it deleted rather than removing the mapping.
Make unmapped records visible
Suppressing rows without a mapping hides the most interesting part of the dataset. Count them. Show them. Let an operator resolve them. The goal is not a clean-looking report; it is a report whose gaps are explicit.
Primary references