Guide · Stripe

Pass the Visitor Into Stripe Checkout With Metadata

How to put a visitor id into a Stripe Checkout Session with metadata or client_reference_id, so every payment can be credited to the traffic source behind it.

· 3 min read

Source lines meeting at a revenue target beside a payment card

If you create Stripe Checkout Sessions on your server, one small change decides whether your revenue can be attributed: putting the visitor's id into the session. Stripe gives you two places to do it.

Option 1: metadata

metadata is a set of key-value pairs you attach to the session. Stripe returns it in the checkout.session.completed webhook.

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [{ price: 'price_123', quantity: 1 }],
  success_url: 'https://example.com/thanks',
  metadata: { df_visitor_id: visitorId, df_session_id: sessionId },
});

Good to know:

  • Metadata on the Checkout Session isn't automatically copied to the PaymentIntent or the Subscription. If you also read those objects later, set payment_intent_data.metadata or subscription_data.metadata too.
  • Keys and values have length limits, and metadata isn't for personal data.

Option 2: client_reference_id

A single string on the session, made for exactly this: linking the session to something in your system.

client_reference_id: visitorId,

Use it when you only need one id. Use metadata when you want several values.

Where the visitor id comes from

The id is created in the browser by your analytics script, so the browser must send it to your server with the "create checkout" request:

  1. 1BrowserReads the visitor and session ids from the analytics script
  2. 2Your serverReceives them with the checkout request
  3. 3StripeStores them on the Checkout Session
  4. 4Webhookcheckout.session.completed returns them with the payment
Visitor id from browser to Stripe

With DataFair, the browser part is one call:

const { df_visitor_id, df_session_id } = window.datafair.attribution();

Send both to your server and put them in metadata. If one Stripe account sells for several websites, add df_site_id too.

Subscriptions and renewals

For subscriptions, the first payment carries the metadata. Renewals arrive later as invoice.paid, with no browser involved. DataFair links renewals to the same subscription, so they keep the source of the first payment and show up in recurring revenue by source.

Payment Links can't take server-side metadata per visitor, but they accept client_reference_id and UTM parameters in the URL. The DataFair script tags buy.stripe.com links on your pages automatically. Payment Links and UTM parameters.

Test it

  1. Create a test-mode session with the metadata.
  2. Pay with a Stripe test card.
  3. Check the event in Stripe's dashboard under Developers → Events and confirm the metadata is there.
  4. In DataFair, the test payment should appear under the source of your test visit.

The full setup, including the webhook, is in Stripe revenue by traffic source.

Related guide: Stripe revenue attribution.

Questions

Should I use metadata or client_reference_id?
Either works for one id. Metadata is better when you want to pass the visitor id and session id together.
Is Checkout Session metadata copied to the subscription?
No. Set subscription_data.metadata if you need it on the Subscription object as well.
What if a payment arrives without metadata?
DataFair tries weaker matches, such as the same customer's email, and reports the rest as unattributed.

Related