How to pass attribution to Stripe Checkout

Stripe Checkout attribution starts before the user leaves your app for checkout.

The important rule is simple: the browser knows the visit context, but the server creates the Stripe Checkout Session. Your frontend should read attribution from AttribIQ and pass it to your backend. Your backend should validate it and write it into Stripe metadata.

Install the tracker

Install AttribIQ on your marketing site and app pages where the checkout can begin.

<script async src="https://edge.attribiq.com/i/a7K4mN2qR8tP.js"></script>

When a visitor lands on the site, the tracker records source, referrer, UTM values, visitor ID, session ID, and landing page context.

Capture attribution before checkout

When the user clicks the upgrade or checkout button, read the attribution object and send it to your backend.

async function startCheckout(priceId) {
  const attribution = window.attribiq?.getAttribution?.()

  const response = await fetch("/api/create-checkout-session", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ price_id: priceId, attribution })
  })

  const { url } = await response.json()
  window.location.href = url
}

This is a transport step. The browser is not deciding the plan, the price, or the payment amount.

Validate on the backend

On the server, validate the input before calling Stripe:

• The requested price ID is allowed for the authenticated user or public checkout.
• The attribution object has the expected shape.
• The project ID belongs to the AttribIQ project you expect for this site.
• String lengths are bounded.
• Unknown fields are ignored or stored only as debug metadata.

Do not allow the browser to decide revenue amount, currency, plan entitlements, or account ownership.

Create the Checkout Session

Use Stripe's server-side Checkout Sessions API. Stripe supports metadata on Checkout Sessions and documents client_reference_id as a reconciliation field.

const attribution = req.body.attribution || {}

const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: priceId, quantity: 1 }],
  success_url: "https://example.com/billing/success?session_id={CHECKOUT_SESSION_ID}",
  cancel_url: "https://example.com/pricing",
  client_reference_id: attribution.visitor_id,
  metadata: {
    attribiq_project_id: attribution.project_id,
    attribiq_visitor_id: attribution.visitor_id,
    attribiq_session_id: attribution.session_id,
    attribiq_landing_page: attribution.landing_page,
    attribiq_utm_source: attribution.utm_source,
    attribiq_utm_campaign: attribution.utm_campaign
  },
  subscription_data: {
    metadata: {
      attribiq_project_id: attribution.project_id,
      attribiq_visitor_id: attribution.visitor_id,
      attribiq_session_id: attribution.session_id
    }
  }
})

Keep metadata small and predictable. Store the identifiers that let AttribIQ join payment events to visits. Use the dashboard for reporting rather than trying to put every marketing field into Stripe.

Test the path

Run a checkout from a URL with UTMs:

https://example.com/pricing?utm_source=newsletter&utm_campaign=launch

After checkout completes, inspect the Checkout Session and Subscription metadata in Stripe. Then confirm the AttribIQ dashboard shows the revenue under the campaign and landing page you used.

If the first payment is attributed but renewals are not, subscription metadata is usually missing.

Next steps

After Checkout metadata is working, connect Stripe to AttribIQ. For the broader model, read Stripe revenue attribution for SaaS.