Documentation

The script reports a referred visit once on arrival. It then reports how long the page was visible: once when the page has been visible for ten seconds, and again on tab hide or page close, skipping a repeat send whose total has not grown since the last one. The beacon sends the page path, never the query string.

The arrival beacon, sent once when the browser reaches your page on a direct affiliate link, carries:

{
  "v": 2,
  "kind": "arrival",
  "key": "pk_0123456789abcdef01234567",
  "clickId": "6f1e3c9a-24b7-4a1d-9f0e-5c8b2a7d4e13",
  "path": "/pricing",
  "client": {
    "languages": "en-US,en",
    "timezoneOffsetMinutes": -60,
    "screenWidth": 1512,
    "screenHeight": 982,
    "hardwareConcurrency": 8
  }
}

token, campaignId and cookieId are accepted on the arrival beacon and not stored in version 2.

On a redirect link, the one your share links use, the click is already recorded server-side before the browser runs, so unless the script posts a visit report (below), the arrival beacon is the browser's only chance to report prior activity. Three more fields ride it there:

{
  "v": 2,
  "kind": "arrival",
  "key": "pk_0123456789abcdef01234567",
  "clickId": "6f1e3c9a-24b7-4a1d-9f0e-5c8b2a7d4e13",
  "path": "/pricing",
  "client": {
    "languages": "en-US,en",
    "timezoneOffsetMinutes": -60,
    "screenWidth": 1512,
    "screenHeight": 982,
    "hardwareConcurrency": 8
  },
  "seenFirstAt": "2026-02-02T18:41:00Z",
  "seenSessions": 3,
  "storageOk": true
}

The engagement beacon, sent once the page has been visible for ten seconds and again on tab hide or page close when the total has grown, carries:

{
  "v": 2,
  "kind": "engagement",
  "key": "pk_0123456789abcdef01234567",
  "clickId": "6f1e3c9a-24b7-4a1d-9f0e-5c8b2a7d4e13",
  "path": "/pricing",
  "visibleMs": 41200
}

A send is accepted only when its click is no more than thirty minutes old: an engagement beacon for an older click is silently dropped, so a fresh organic session on a device carrying a days-old referral cookie can never overwrite that old click's own measurement. What is kept is the maximum of every accepted send for that click, never the last one, so a visitor who tabs away at two seconds and comes back to read for ten minutes still gets credit for the cap above, sixty seconds, not the two. A referred visit that never sends an engagement beacon at all leaves this column empty, not zero: empty means unmeasured, zero means measured and instant, and fraud review treats the two differently.

The script keeps a second cookie, alterion_seen, recording that a visitor was on your site before they arrived through an affiliate link. It holds three values: when they were first seen, when they were last seen, and how many separate visits that adds up to. It is written only on a visit that carries no referral link, and writing it sends no request: a visitor who never clicks an affiliate link produces no record of themselves on our side. The script does still fetch its configuration from Alterion Labs on every page load, referred or not, and that request only confirms your installation is live. Visits are counted by a thirty-minute gap, so browsing several pages in one sitting counts once.

When a referred visitor arrives on a direct link, the script always reports what that cookie held, alongside the referral it was already reporting. On a redirect link it reports only when storage is confirmed working, and says nothing at all when storage is blocked, because that click is already recorded server-side with nothing left to add. We record the answer on the click: prior activity, no prior activity, or unknown. Unknown is what we record when the browser blocks cookies, when the cookie cannot be read, or when it claims a first-seen time in the future, because none of those is the same as a visitor who had never been to your site, and reporting them as no prior activity would quietly overstate how cold your referrals were. On a redirect link where nothing was reported, the column is left null rather than stamped unknown, which reads the same way to anyone querying it.

seenFirstAt, seenSessions and storageOk ride on the visit report whenever the script sends one, and otherwise on the arrival beacon for a redirect link, because that click is recorded before the browser runs. All three are optional and an absent field is not a zero. Once a beacon request passes rate limiting and validation, it answers ok whatever happens, it never blocks the page, and a second report for the same click is accepted and ignored. The visit endpoint below is less forgiving. It fires on a direct link, and on a redirect link only when first-touch is on and the visitor already holds a referral cookie, so we can decide whether that earlier referral still holds. That visit resolves to the click the redirect already recorded. An unrecognised key answers {"ok": false}, and a database write failure answers a 500.

{
  "v": 2,
  "key": "pk_0123456789abcdef01234567",
  "token": "9f2c1a4e7b3d",
  "cookieId": "66b77216-c14b-48b9-b980-695a08e97e02",
  "heldToken": "4b8e0d2c6a1f",
  "framed": false,
  "landingUrl": "https://your-site.com/pricing?via=9f2c1a4e7b3d",
  "referrer": "https://a-partner-review.com/best-tools",
  "seenFirstAt": "2026-02-02T18:41:00Z",
  "seenSessions": 3,
  "storageOk": true
}

Call this on your success page. We attribute it from the referral cookie, so the page never sees affiliate identity.

alterion.convert({
    orderId: "ORDER_ID",       // your unique order/invoice id
    amountCents: 4900,         // integer cents
    currency: "USD",
    customerId: "CUSTOMER_ID", // enables recurring attribution
    // newCustomer: true       // send true when this buyer has never paid you before
});

alterion.convert() takes your order id, the amount in the currency's smallest unit (cents for USD and EUR, yen for JPY), the currency and your customer id, for a sale. Skip the order id on a page carrying a Stripe checkout session id: the script reads it from the URL and uses that instead. Skip the customer id and the sale still records, but as an anonymous conversion: it can never be correlated with any other sale, so it earns exactly one commission, is never capped, is never halted by a cancellation, and can never renew, even on a recurring campaign. Send it whenever you can. A signup, which carries no order, is reported with alterion.signup() below instead. The script adds the rest of the payload itself.

{
  "v": 2,
  "key": "pk_0123456789abcdef01234567",
  "orderId": "cs_test_a1b2c3",
  "merchantOrderId": "ORD-1041",
  "amountCents": 4900,
  "currency": "USD",
  "type": "sale",
  "customerId": "cus_QX1a2b3c",
  "token": "9f2c1a4e7b3d",
  "cookieId": "66b77216-c14b-48b9-b980-695a08e97e02",
  "client": {
    "languages": "en-US,en",
    "timezoneOffsetMinutes": -60,
    "screenWidth": 1512,
    "screenHeight": 982,
    "hardwareConcurrency": 8
  },
  "test": false,
  "newCustomer": true
}

This is what leaves the browser when the call declares newCustomer. orderId is the Stripe checkout session id when one is on the page and your own order id otherwise, merchantOrderId carries your order id alongside it, token and cookieId come from the referral cookie, and client is the coarse device signature described under Privacy guidance. A merchant posting to this endpoint directly, rather than through alterion.convert(), may also send code (a redeemed referral code, handled the way the postback describes it below) and customerEmail.

Call this from your post-signup page. It gives a trial that converts later a marker to attribute through once your referral cookie is gone, on top of whatever the cookie itself already covers. It records no amount and mints no commission on its own.

alterion.signup({
    customerId: "CUSTOMER_ID",       // enables the later paid event to inherit this signup
    customerEmail: "CUSTOMER_EMAIL", // used when customerId is not available yet
    // newCustomer: true             // send true when this buyer has never paid you before
});

alterion.signup() takes your customer id, your customer's email, or both, at least one of the two. It sends nothing when neither is set, and nothing when the referral cookie is gone: there is nothing to attribute through.

The paid event inherits the affiliate through customer identity, not through anything the paid call sends about the referral itself: send the same customer id or the same email on the paid call that you sent here. That identity is the join. A paid event carrying no matching identifier finds no signup to join, records as organic, and pays no commission, with no error anywhere to say why.

This path needs a connected account: connect your Stripe account to Alterion Labs first. Every event on an unconnected account is dropped, not queued, so skip this step and you get no conversions, no renewals and no reversals from Stripe.

Pass the referral token as client_reference_id on Stripe Checkout. We read it on the completed checkout.

// When creating the Checkout Session on your server:
const session = await stripe.checkout.sessions.create({
    // ...your line items...
    client_reference_id: alterionToken, // read via alterion.token() on the client
    success_url: "https://your-site.com/thanks?session_id={CHECKOUT_SESSION_ID}",
    metadata: { alterion_order_id: "ORD-1041" },
});

Add the checkout session id to your success URL, as shown above. The tracking script reads it and reports the sale under the same id Stripe uses, so a sale you report from your success page and the same sale arriving from Stripe are recognised as one.

Send your own order reference in the Stripe event metadata as well, under alterion_order_id or order_id. It covers the sale your other path did not report under Stripe's own id: when the two references match within the hour, we merge the two reports into one sale, filling in whatever the first left blank and never overwriting what it already recorded. A sale both paths already report under Stripe's own id is recognised as one before the reference is read, and there the Stripe report corrects the amount your own path sent. Do not put your order reference in client_reference_id; that field carries the referral token. When a Stripe sale arrives with no reference and matches one already recorded under the same customer key (Stripe's own customer id, or the buyer's email when there is none), the same amount and the same currency within the hour, we hold it and ask you rather than paying twice.

Renewals, and refunds and chargebacks that Stripe reports, reach Alterion Labs through Stripe. If your Stripe account is not connected to Alterion Labs, post reversals yourself to the refund endpoint below, and post a cancellation yourself to the endpoint further below the moment a subscription ends. The tracking snippet records what you call it for and nothing on its own: a sale recorded by alterion.convert() is never reversed unless you report the reversal, and a recurring commission is minted only when you report that customer's renewal yourself, through alterion.convert() or the postback. Call it once at checkout and nothing else, and nothing else ever generates, cancellation reported or not. Only a connected Stripe account reports its own renewals for you.

newCustomer is the one fact only your database knows: send true when this buyer has never paid you before. The line ships commented out on purpose. Alterion Labs does not guess this from your sales with our partners, because we only see the sales partners brought you: a customer who has bought from you ten times directly looks new to us, and pricing them as new is exactly the overpayment this setting exists to prevent. Until it arrives, we fall back to Stripe, then to your campaign's setting. A sale that inherits from a signup carries the status the signup already resolved to. When the signup left it unanswered, the sale resolves it once, the same way, and that answer is final.

Leaving the field out is not the same as sending false. Out means you have not told us, and we fall back to Stripe or to your campaign's setting. Sending false on every call tells us every one of your buyers is a returning customer.

A redirect affiliate link sets two cookies from our server once a visitor opens it. alterion_ref_<campaignId> holds the referral for that campaign and lasts for the campaign's cookie window. alterion_cid holds a random device identifier and lasts 400 days. Both are httpOnly, so no script on your page can read them. A browser prefetching the link in the background sets neither cookie until a visitor actually opens it.

alterion_ref holds the referral: which partner sent the visitor, and the identifiers that let a later sale resolve back to them. It is written only on a visit that arrives through an affiliate link, and it lasts for your campaign's cookie window.

alterion_seen holds prior activity: when the visitor was first seen on your site, when they were last seen, and how many separate visits that adds up to. It is written on ordinary visits that carry no referral link, and it lasts sixty days. Its contents never leave the device on an unreferred visit, and no record of that visitor exists on Alterion Labs' side unless and until they arrive through an affiliate link. The script does fetch its configuration from Alterion Labs on every page load, referred or not. That request carries your public key and, as any web request does, the visitor's IP address and user agent. It records that your installation is live, and it creates no visitor record.

alterion_probe is set with a ten-second lifetime, then read back and deleted immediately, when the script needs to establish whether the browser keeps cookies at all. It carries no information about the visitor.

The three the script writes are first-party cookies on your own domain. The two the redirect sets belong to whichever domain serves your referral links. Until Alterion Labs provisions the certificate and the CDN alias for your own tracking domain, that is the Alterion Labs platform origin, so those two are third-party cookies from your site's point of view. Connecting your own tracking domain makes them first-party. The two the script writes for the referral and for prior activity are scoped to your own domain and are never read on another merchant's site. The device identifier the redirect sets belongs to the domain that serves referral links, which today is shared across every Alterion Labs merchant, so the same cookie is read when that visitor follows another merchant's link. What we record on that merchant's click is derived from it with a key unique to their workspace, so one merchant's record of a device and another's cannot be compared. Merchants never see one another's records. The device signature described below is hashed separately for each workspace and cannot be compared across them.

The script records whether the referred page loaded and how long it was visible, up to sixty seconds. It records no scroll depth, no keystrokes, and no pointer or scroll event counts. It records a coarse device signature made of the browser and operating system family, the language list, the timezone offset, a rounded screen size and a processor count collapsed into three bands. No canvas, audio or font fingerprinting is used. Raw IP addresses are never stored in your program's records. The address is used in memory to classify the request and to rate-limit it, and only a salted hash is kept.

When a visitor arrives through a direct affiliate link, the script sends the address of the page they landed on, including its query string, and the address of the page that referred them. Both are recorded on the click. The arrival and engagement reports send the page path on its own, without the query string, and version 2 does not store it.

On a referred arrival we also record what any web server sees: the browser's user agent string, its language header, its fetch-metadata headers, and the country the visitor's network resolves to. On a conversion, the script sends what you passed to alterion.convert(), meaning your order id, the amount, the currency, your customer id, and, when you send it, the customer's email address, which is stored only as a hash, alongside the referral token and cookie identifier it reads from its own cookie, the coarse device signature described above, and whether you marked the call a test or declared the buyer new or returning. A signup sends the same referral token, cookie identifier and device signature, plus whichever of a customer id or an email you passed to alterion.signup(), from an ordinary post-signup page view, not only a paid one. The email is stored only as a hash there too.

On a referred arrival it also reports what alterion_seen held, when it can: we record three facts on the click, whether there had been prior activity, when it started, and how many visits it covered, unless storage is blocked, in which case none of the three is recorded. A redirect link reports the same three facts on the arrival beacon, since that click is already recorded server-side, or on the visit report when the script sends one. We do not record which pages were seen.

The device signature is hashed with a secret key and your workspace's own identifier before it is stored, so the stored value differs in every workspace and cannot follow a visitor to another merchant. A customer email address that arrives on a conversion or a signup is hashed the same way. Neither hash is reversible and neither is shared.

Storage on a visitor's device is in scope in the EU whether or not anything is transmitted, and alterion_seen is written on ordinary page views rather than only on referred ones. Take your own legal advice on whether your consent banner must gate it.

If your banner blocks storage, we write no cookie. The configuration fetch, the beacons and the client blob still go. On a direct affiliate link, the script reports that storage was blocked, and we record the visitor's prior activity as unknown rather than guessing; on a link that redirects through us first, nothing is reported at all, and the same column stays null, which reads the same way. A browser that cannot keep a cookie is not the same as a visitor who had never been to your site, and we will not report the two as one number.

Name the five cookies and what each holds, and say that two of them are third-party cookies served from the Alterion Labs platform domain until you connect your own tracking domain, and that the device identifier cookie is set on that same domain for every merchant until then, while the value recorded against your account is derived for your workspace alone. Say that a third party processes referral and conversion data on your behalf. Say that how long a referred page stayed visible, up to sixty seconds, is recorded. Say that a coarse device signature is collected and hashed for fraud detection. Say that the landing page address, including its query string, and the referring page address are recorded on a referred arrival. Say that prior activity on your site is recorded on a referred arrival: whether there had been any, when it started, and how many visits it covered. Say that a customer identifier or email address you send us when a visitor signs up is recorded too, from an ordinary post-signup page view, with an email address stored only as a hash the same way a conversion's is. Alterion Labs' own privacy policy describes the processing in Section 11.