Affiliate Tracking and Attribution Reference

Use this guide to choose the right affiliate URL parameter and understand how browser attribution persists. For complete script options and runtime method details, see Tracking Script Reference.

Canonical URL Parameter

Use ?via=TOKEN for affiliate token attribution.

Optional Custom Parameter Names

You can define additional token parameter names with script attribute:

<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 this for controlled return links where you already know the generated referral ID. 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

In Setup or Settings, add first-party hosts under Approved site or app hosts in Tracking domains. Enter hostnames only, one per line, without a scheme or path. AffiliateBase returns the account-approved host list from /api/track so the script can continue attribution across your own sites or 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 only with their valid parent domain. Browser storage is account-scoped, so referrals are kept separate between AffiliateBase accounts.

First-party continuity and cross-domain tagging

Approved first-party links are handed off 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, expired, or the destination is no longer approved, no new attribution is applied. Navigation and checkout still continue, and an already-valid destination referral remains 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 and use a bounded wait 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, blocked, or the wait times out, continue checkout without a referral rather than blocking the purchase.

Identify a referred signup

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

This records a lead email. It does not 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