Attribution and tracking

Attribution is the part of an affiliate program that has to be beyond doubt: partners only promote what they trust to count. This guide covers how tracking works, how to prove your install, and what to do when a sale arrives unattributed.

How tracking works

The script is one tag:

<script async src="https://app.affiliaterail.com/rail/v1/rail.js" data-rail="prg_xxxx"></script>

When a visitor lands with a referral parameter in the URL, the script records a click and stores the referral in a first-party cookie named rail_referral on your registrable domain, plus localStorage as a fallback. acme.com, www.acme.com and app.acme.com all see the same cookie. The attribution window (60 days by default, set under Program settings, Attribution) is written onto the click when it happens, and the first touch wins within the window: a second partner's link does not steal a referral that is already running.

The script watches for these parameters, first one present wins: rail, ref, aff, via, fpr, tap_s, lmref, tolt, afmc, ali, f2f-ref. The first is ours and the second is your default; the rest are the parameters other affiliate platforms use, captured so that links published before you migrated keep converting. Your own parameters are configurable under Program settings, Attribution.

If your funnel crosses registrable domains (marketing on acme.com, checkout on getacme.io), list the second domain in the tag's data-domains attribute; the script carries the referral across in the link and strips its parameter from the address bar afterwards.

Getting the sale attributed

Four paths bind a paying customer to a partner. Use whichever fits how you charge; they can coexist.

1. Stripe Checkout, Payment Links, Pricing Tables, Buy Buttons. Nothing to build. The script stamps the checkout's client_reference_id automatically, including on elements added to the page after load, and never overwrites a value you set deliberately.
2. Server-side metadata. For Stripe Elements or any server-driven flow: read the rail_referral cookie, pass its click id as metadata.rail_referral on the customer, subscription or checkout session. Three lines of code; Server-side attribution has them in Node, Next.js and Python.
3. Coupons. Assign a partner a Stripe promotion code and sales using it attribute even without a click. Podcast and video audiences convert this way.
4. Leads and the API. Approved leads and API-created customers bind explicitly, and run through the flow engine like everything else.

Binding is idempotent on the Stripe customer: the first event that carries a referral wins, and later ones change nothing.

Prove the install

Insights, Attribution health, Check my install. Enter a page URL or let it use your homepage. Three checks, each a pass or a failure with the fix written out:

1. Tag found. The page is fetched and parsed. Failures distinguish a missing tag, a tag without data-rail, another program's id, and an unexpected host.
2. Click recorded. A synthetic click is driven through the real click endpoint with your page's origin, proving the path your visitors will take. The test click and everything it created are deleted afterwards.
3. Cookie domain. Which registrable domain the referral cookie lands on, and who sets it. When a tracker domain of your own is live, the server sets the cookie and Safari honours the full window; a script-set cookie is capped at seven days there.

Attribution health

The same page tracks the ongoing truth: sales seen, attributed, unattributed and the rate, over 7, 30 or 90 days, split by path (link, coupon, lead, metadata). Every unattributed sale appears with what was missing, in plain words:

• No click id on the checkout
• A click id we never issued
• A click from another program
• The click's window had closed
• No checkout session or customer event seen

each with the likely fix. You can attribute a sale by hand from the row; doing so also picks up every other missed invoice of that customer.

Test mode

Everything above works identically in Stripe test mode. Connect a test account, click your own link, pay with the test card, and watch the sale land as attributed. The quickstart runs this loop end to end.