Trace docs

Trace ties every Stripe charge back to the ad, post, or referral that drove the visitor — server-side, refund-aware, post-iOS-17. This guide gets you from zero to a working dashboard in about three minutes.

The 3-step quickstart

1. Drop the tracking script

Paste this once in the <head> of your store. Replace site_xxxwith the Site ID from your dashboard's Settings tab.

html

<script defer
  src="https://tracerev.com/track.js"
  data-site="site_xxx"></script>

That's it for tracking. Pageviews fire automatically, UTMs are captured, and a first-party cookie holds the visitor ID for 1 year. More on the script →

2. Connect Stripe

In your dashboard, open any site → Settings → click Connect Stripe. We use Stripe Connect's read-only OAuth — no card numbers, no payment access, just charges and refunds.

Within a minute or two, your last 12 months of charges are backfilled and new charges stream in via webhook. More on Stripe Connect →

3. (Optional) Wire the SDK into your custom checkout

If you're running a custom Stripe Checkout flow (not Shopify, not WooCommerce, but a bespoke one), install the SDK and pass trace_visitor_idin your Checkout Session metadata. This is the most accurate attribution path because it doesn't depend on email matching.

bash

npm install @trace/sdk

// app/api/checkout/route.ts (Next.js App Router)
import { getAttribution } from '@trace/sdk/next';
import Stripe from 'stripe';

export async function POST() {
  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
  const session = await stripe.checkout.sessions.create({
    mode: 'payment',
    line_items: [/* your line items */],
    success_url: 'https://yourstore.com/thanks',
    cancel_url: 'https://yourstore.com/cart',
    metadata: await getAttribution(),  // adds trace_visitor_id
  });
  return Response.json({ url: session.url });
}

Full SDK reference →

Already done? Open your dashboard.

Your Attribution tab populates as soon as charges flow through. If a charge shows up as unattributed, see troubleshooting.

What's in the rest of these docs

Install the script — full reference for the pixel, what cookies it sets, and what data it sends
Connect Stripe — what we read from your account, the 12-month backfill, and disconnecting
SDK reference — Next.js (App + Pages Router), Express, browser, generic Node
Identify users & custom events — capture emails for the email-fallback attribution path
Troubleshooting — pixel not firing, unattributed charges, missing UTMs

How attribution actually resolves

For each Stripe charge, Trace tries three paths in order to find the visitor who drove it:

Metadata. If your Checkout Session has metadata.trace_visitor_id, we use it. This is what the SDK gives you.
Email match. If the customer email matches an identify()call we've seen, we use that visitor.
Unattributed. Charge still counts toward revenue, but no channel is credited.

Once we have a visitor ID, we look up their earliestevent with a UTM or referrer and credit that. This is "first-touch" attribution. Last-touch is on the v2 roadmap.