Skip to content
ADVISORY RECONCILIATION · STRIPE ↔ ENTITLEMENTSRun the browser-only CSV audit
The journal
ArchitectureNovember 14, 2026 · 7 min read

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.

FROM READING TO EVIDENCE

Your exports are more interesting than our examples.

Run the local reconciliation and see which categories actually appear in your data. The audit needs no account.