Attribute Stripe Checkout payments

When your server creates a Checkout Session, copy the visitor ID into its metadata. Works for hosted and embedded Checkout, one-time and subscription mode.

First connect Stripe so payments are imported: see Connect Stripe.

Set it up

1. Send the visitor ID with the checkout request

   Read it in the browser and include it in the request to your own checkout endpoint:

   Browser

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   // When the visitor clicks your checkout button.
   async function startCheckout(plan) {
     const response = await fetch("/api/checkout", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ plan, visitorId: window.analytics?.getVisitorId() ?? null }),
     });
     const { url } = await response.json();
     window.location.assign(url);
   }

2. Add metadata to the Checkout Session

   Put the keys on the session and on the object Stripe creates from it: payment_intent_data.metadata for one-time payments, subscription_data.metadata for subscriptions. Then renewals carry the same attribution.

   One-time payment (mode: payment)

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   13

   14

   15

   // In your existing server-side checkout handler.
   // stripe is your initialized Stripe client; visitorId came from your browser.
   const attribution = {
     metricraven_visitor_id: visitorId || "",
     metricraven_user_id: authenticatedUser.id,
     metricraven_plan: "pro",
   };
   const session = await stripe.checkout.sessions.create({
     mode: "payment",
     line_items: [{ price: "YOUR_STRIPE_PRICE_ID", quantity: 1 }],
     success_url: "https://example.com/success",
     cancel_url: "https://example.com/pricing",
     metadata: attribution,
     payment_intent_data: { metadata: attribution },
   });

   Subscription (mode: subscription)

   Copy

   1

   2

   3

   4

   5

   6

   7

   8

   9

   10

   11

   12

   13

   14

   // Subscription checkout uses subscription_data instead of payment_intent_data.
   const attribution = {
     metricraven_visitor_id: visitorId || "",
     metricraven_user_id: authenticatedUser.id,
     metricraven_plan: "pro_monthly",
   };
   const session = await stripe.checkout.sessions.create({
     mode: "subscription",
     line_items: [{ price: "YOUR_RECURRING_STRIPE_PRICE_ID", quantity: 1 }],
     success_url: "https://example.com/success",
     cancel_url: "https://example.com/pricing",
     metadata: attribution,
     subscription_data: { metadata: attribution },
   });

   For a guest checkout without an account, leave out metricraven_user_id.

3. Identify signed-in users (recommended)

   Calling Identify when a user signs in links later payments to them by metricraven_user_id, even if the visitor ID was missing at checkout.

Metadata keys