Docs · Guide

Revenue attribution

Revenue attribution is crediting each payment back to the marketing that produced it — the source, landing page and campaign a customer first arrived through, rather than the last click before checkout. Statlark already records that first touch for every visitor; connect Stripe and each payment is tied to it, so 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. Prefer npm? Install the JavaScript SDK instead — the same tracker, initialized in code, with a React provider.

Installing for visitors in the EU or UK? The default tracker sets a first-party analytics cookie, which needs prior consent there. Either gate it behind a cookie-consent banner — full attribution once the visitor accepts — or switch to cookieless mode, which sets no cookie and needs no banner.

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_vidcookie server-side and stamp it onto the Stripe Checkout Session, using Stripe’s own client_reference_id field — it exists precisely to carry your own identifier through checkout. 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:

Copy the webhook endpoint URL shown there. In Stripe → Developers → Webhooks, add an endpoint pointing at it.
Subscribe the endpoint to checkout.session.completed, invoice.paid and charge.refunded (the last one nets refunds out of your revenue — see below).
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:

client_reference_id on the Checkout Session — the primary, Stripe-native field.
session.metadata.statlark_visitor_id — the fallback, for flows that already use client_reference_id for something else.
subscription metadata on invoice.paid — keeps renewals attributed.
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.

5. Refunds and net revenue

Statlark reports netrevenue: a refund is subtracted from every figure it touches — the Overview headline, each traffic source and landing page, and each customer’s lifetime value. Subscribing your webhook to charge.refunded (step 3) is all it takes; refunds then net out automatically as they happen.

A refund is credited against the original sale— the same visitor, source and date that earned it — so it lowers the period the purchase was made in, not the period the refund was issued. That keeps a channel’s revenue honest: money it brought in and later gave back nets to what it truly earned. (One consequence: a refund of an older sale won’t show in a window that doesn’t include the original purchase date.) Statlark matches a refund back to the original charge — one-time or subscription — so it only nets out when that payment was recorded through Statlark.

Not on Stripe — or need to record a refund or correct a mistaken sale by hand? Do it from your own server with the REST API.

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 card 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 card — 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.

Last reviewed 2 August 2026