Statlark
Docs · Guide

Revenue attribution

Statlark already knows which marketing source first brought each visitor to your site. Connect Stripe and every payment is tied back to that visitor — so your revenue lines up next to the channels that earned it. Statlark never holds a Stripe API key; every signal rides along in the events you already send.

1. Install the tracker

Drop this one line into the <head> of every page. Your live site ID is already filled in for you under Settings → Install in your Statlark dashboard — copy it from there.

<script
  defer
  src="https://statlark.com/script.js"
  data-website-id="YOUR_SITE_ID"
></script>

The dashboard flips to live the moment your first event lands, usually within seconds. That alone gives you traffic and sources; the steps below add revenue.

2. Attribute your revenue

There are two ways to connect a payment to a visitor. Pick based on how much checkout code you want to touch — you can also do both, and the most reliable signal wins.

Email stitch (lightest — no checkout changes)

Whenever you learn a visitor’s email, tell Statlark. When a Stripe payment arrives, Statlark matches its customer_email to that visitor. Nothing in your checkout has to change.

// Call this once you know who the visitor is — e.g. right after they sign in.
// The script is deferred, so guard for it.
window.statlark?.identify({ user_email: "buyer@example.com" });

Checkout stamping (most accurate — covers anonymous buyers)

Read the first-party _slk_vid cookie server-side and stamp it onto the Stripe Checkout Session. This attributes buyers even when you never learn their email.

// Read the Statlark visitor id from the Cookie header (server-side).
export function readStatlarkVisitorId(cookieHeader: string | null): string | null {
  if (!cookieHeader) return null;
  for (const part of cookieHeader.split(";")) {
    const [key, ...value] = part.trim().split("=");
    if (key === "_slk_vid") return decodeURIComponent(value.join("="));
  }
  return null;
}

For a one-time payment, pass it when you create the session:

const visitorId = readStatlarkVisitorId(req.headers.get("cookie"));

const session = await stripe.checkout.sessions.create({
  mode: "payment",
  line_items: [/* … */],
  success_url: "https://example.com/thanks",
  cancel_url: "https://example.com/pricing",
  client_reference_id: visitorId ?? undefined,                          // primary signal
  metadata: visitorId ? { statlark_visitor_id: visitorId } : undefined, // fallback
  customer_email: customerEmail,                                        // helps email stitch
});

For subscriptions, also stamp subscription_data.metadata so that renewals stay attributed — renewal invoices have no checkout and no browser cookie, so the metadata is the only thread back to the original visitor.

const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [/* … */],
  success_url: "https://example.com/thanks",
  cancel_url: "https://example.com/pricing",
  client_reference_id: visitorId ?? undefined,
  customer_email: customerEmail,
  subscription_data: {
    // Copied onto every future renewal invoice — this is how attribution
    // survives past the first charge.
    metadata: visitorId ? { statlark_visitor_id: visitorId } : {},
  },
});

3. Connect Stripe

You create the webhook in your own Stripe dashboard and hand Statlark only the signing secret — we never ask for a Stripe API key. In Statlark, open Settings → Revenue (Stripe) for the site, then:

  1. Copy the webhook endpoint URL shown there. In Stripe → Developers → Webhooks, add an endpoint pointing at it.
  2. Subscribe the endpoint to checkout.session.completed and invoice.paid.
  3. Copy the endpoint’s signing secret (whsec_…) and paste it back into the Stripe section in Statlark. It’s stored encrypted and never shown again.

That’s it — new payments start attributing as they come in.

4. How attribution resolves

When a payment event arrives, Statlark resolves the visitor in this order, taking the first signal it finds:

  1. client_reference_id on the Checkout Session — the primary, Stripe-native field.
  2. session.metadata.statlark_visitor_id — the fallback, for flows that already use client_reference_id for something else.
  3. subscription metadata on invoice.paid — keeps renewals attributed.
  4. email stitch — match the Stripe customer_email to a visitor who called identify().

A payment that matches none of these is still recorded — it just shows up as unattributed revenue rather than being dropped.

Track a goal

A goal is any conversion you care about — signup, purchase, pro_upgrade. You don’t create goals in the dashboard; you fire them from your site, and the Goals tab lists each name automatically with its conversion rate, top sources, and (once Stripe is connected) the revenue it drove. Fire one the moment the conversion happens:

// Fire a goal the moment a conversion happens — e.g. right after a signup.
// The script is deferred, so guard for it.
window.statlark?.goal("signup");

// Optional: attach properties — captured with the event for later analysis.
window.statlark?.goal("pro_upgrade", { plan: "pro" });
<!-- Or fire one on click, no JavaScript required. -->
<button data-statlark-goal="signup">Create account</button>

The first time a goal fires it appears on the Goals tab — no dashboard setup, no configuration. Once Stripe is connected, Statlark also emits payment, subscription_started, and subscription_renewed goals automatically. See Goals & conversions for goal properties, the #1 KPI, and conversion alerts.