Skip to main content
AffiliateBase
Features Pricing Compare Help
Log in Start for free

Affiliate Tracking and Attribution Reference

Reference AffiliateBase URL parameters, referral cookies, cross-domain tagging, signup identification, and generated referral IDs.

Table of Contents

This guide is for merchants and developers who run the AffiliateBase tracking script. It explains which URL parameter carries an affiliate token, how a referral persists in the browser, and how attribution crosses your own domains. For every script option and runtime method, see Tracking Script Reference.

Standard URL parameter

Use ?via=TOKEN for affiliate token attribution.

Optional custom parameter names

You can add token parameter names with a script attribute:

HTML
<script
  async
  src="https://app.affiliatebase.io/track.js"
  data-account-id="YOUR_ACCOUNT_ID"
  data-affiliatebase-params="partner,invite">
</script>

Automatic capture uses this one script tag; it does not require the command-queue preloader. If advanced code calls affiliatebase(...) before the remote script loads, use the preloader shown in the Tracking Script Reference.

Referral preload

?referral=<referral_id> preloads an existing referral.

Use it for return links you control, when you already know the generated referral ID. Treat the ID like an affiliate link: any browser that opens the URL is attributed to that referral, so only send it to the visitor it belongs to. AffiliateBase rejects, and gives no attribution to, expired or deactivated referrals, referrals whose affiliate is no longer pending or active, and referrals in archived campaigns. To carry a referral across your own domains, use approved-host handoff (below) instead of sharing raw referral IDs. A bare referral UUID or account ID does not create cross-domain handoff authority, and a public ?via token is not a Stripe client_reference_id.

Approved hosts and browser state

Add first-party hosts under Approved checkout hosts in Settings -> General (called Approved site or app hosts in Setup step 2). Enter hostnames only, one per line, without a scheme or path. AffiliateBase returns this approved host list from /api/track so the script can carry attribution across your own sites and apps. The tracker refreshes this list and handoff configuration on page load and when the page regains focus.

The standard one-tag installation does not require data-domains. An optional data-domains script or per-link hint only narrows the approved list for that link; it cannot authorize an arbitrary host or a third-party checkout page.

Cookies are host-only by default. Use data-cookie-domain only when sibling subdomains need to share attribution, and set it only to their valid parent domain. Browser storage is scoped to your account, so referrals stay separate between AffiliateBase accounts.

First-party continuity and cross-domain tagging

The tracker hands off approved first-party links automatically. When a referred visitor follows a link to another approved host, the tracker requests a short-lived encrypted ab_handoff capability and adds it to the link. It is bound to the account, source host, destination host, selected referral, and the existing visitor session. The destination redeems it to restore the same referral UUID, visitor session, and original referral expiry; it does not create a new referral or visitor session. The tracker removes the reserved parameter promptly after processing.

Use optional data-domains only to narrow the account-approved destinations for a link. It cannot authorize an arbitrary host or a third-party checkout page. The handoff requires an existing visitor-session proof, so do not construct ab_handoff links yourself or try to mint one from a public referral UUID or account ID.

If the capability is invalid or expired, or the destination is no longer approved, no new attribution is applied. Navigation and checkout continue, and an already-valid referral on the destination stays in place. Retrying a still-valid capability is safe and restores the same referral/session without creating another referral. Merchant-owned via, referral, and coupon query values and hash fragments are preserved.

For advanced custom Checkout flows, check that the tracker is available, then wait (with a time limit) for window.AffiliateBase.whenAttributionReady() or affiliatebase('ready', callback) before submitting referral_id. The structured result reports none, pending, succeeded, failed, or blocked. If the script is missing or blocked, or the wait times out, continue checkout without a referral instead of blocking the purchase.

Identify a referred signup

JavaScript
affiliatebase('identify', { email: 'customer@example.com' });

This records a lead email. It doesn’t record a purchase or create a commission. For purchases, pass the generated referral ID to Stripe and verify webhook delivery. See the tracking reference for asynchronous results and server conversions.

Notes

  • Use via as the default token parameter
  • Keep referral and checkout flows on HTTPS in production
  • Keep the default host-only cookie unless sibling subdomains require a valid parent-domain cookie
  • For API endpoints and auth, see REST API Overview
Esc