Install the Affiliate Tracking Script

This page is for the person who edits your site layout or checkout code. It covers adding the AffiliateBase tracking script and passing the generated referral ID to Stripe Checkout.

To get the script with your account ID filled in, open Setup step 4 (Integration), choose and save the attribution path that matches your site, then expand Add tracking -> View developer steps. The code stays collapsed so the checklist shows one action at a time. Before you can verify payment attribution, connect Stripe in Setup step 1 (see Connect Stripe for Affiliate Tracking).

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

Replace YOUR_ACCOUNT_ID with your account ID. The snippet shown in View developer steps already contains it, so copy it with Copy script. If you have set Approved site or app hosts, the copied snippet also includes a data-domains attribute listing them. Paste the script in the global layout or a site-wide custom-code area, before </body>.

Receive script updates automatically

This URL receives approved, compatible tracking updates with no change to your snippet. Keep your existing consent-manager rules: load the script only when permitted. Pages that are already open keep the version they loaded until the next page load.

If you previously installed a numbered CDN URL, replace that URL with https://app.affiliatebase.io/track.js. Keep your account ID and other attributes. Replace the existing tag; do not add a second copy. If your site uses Content Security Policy, allow app.affiliatebase.io in both script-src and connect-src.

The script sends a small installation diagnostic with its version and script source. The diagnostic does not create a referral or sale. To turn it off, set data-telemetry="false". Developers who need explicit version control can see the tracking reference.

This single script tag is the automatic-install path and needs no separate command-queue preloader. If advanced code calls affiliatebase(...) before the remote script loads, add the preloader before this tag and wait for affiliatebase('ready', ...) before using the result.

If your first-party journey spans multiple sites or apps, add their hostnames under Approved site or app hosts in Setup step 2 or Settings → General. Enter one hostname per line, without a scheme or path. AffiliateBase supplies this approved list to the script, which refreshes it on page load and when the page regains focus. You do not need to hand-write data-domains; the copied setup snippet includes it when hosts are saved. Optional data-domains hints can narrow approved hosts for a link, but they cannot authorize arbitrary hosts.

Attribution uses host-only cookies by default and account-scoped browser storage. Add data-cookie-domain only when sibling subdomains need to share a valid parent-domain cookie.

Continue the same referral across approved domains

When a referred visitor follows a link to another approved host on your own domains, the tracker adds a short-lived ab_handoff parameter to the link. The destination page uses it to keep the same referral and its original expiry, then removes it from the URL. No new referral is created.

You don’t need to do anything to make this work. Don’t build or edit ab_handoff links yourself, and don’t copy them into emails, ads, or bookmarks: they expire after a few minutes and only work for the visitor who clicked. If one has expired, or the destination is no longer on your approved list, the visitor still reaches the page and can check out, but that page doesn’t pick up the referral. Your own via, referral, coupon, and # values in the URL are left alone.

This continuity applies to approved first-party hosts. Stripe-hosted and other third-party checkout pages still need the Stripe or server-side handoff described below.

Add Stripe checkout attribution

Most Stripe-hosted setups need only the script on the same published page as the Stripe checkout link or element.

Payment Link

If your site links to a Stripe Payment Link, keep your existing https://buy.stripe.com/... links unchanged:

<a href="https://buy.stripe.com/your_payment_link">Buy now</a>

The script detects buy.stripe.com and link.payment links automatically. For any other Payment Link URL, add the data-affiliatebase attribute to the link.

Buy Button or Pricing Table

Keep the Stripe element on the same page as the AffiliateBase script:

<stripe-buy-button buy-button-id="buy_btn_xxx" publishable-key="pk_live_xxx"></stripe-buy-button>

<stripe-pricing-table
  pricing-table-id="prctbl_xxx"
  publishable-key="pk_live_xxx"
></stripe-pricing-table>

Custom or Backend-created Checkout Sessions

If your server creates Checkout Sessions, first submit the referral ID to your server:

<form action="/checkout" method="post" data-affiliatebase data-affiliatebase-param-name="referral_id">
  <button type="submit">Start checkout</button>
</form>

Then set client_reference_id on your server when you create the Stripe Checkout Session. Where your Checkout mode supports it, copy the same generated referral ID into affiliatebase_referral_id metadata:

referral_id = params[:referral_id].presence
referral_metadata = { affiliatebase_referral_id: referral_id }.compact

checkout_params = {
  success_url: "https://example.com/success",
  cancel_url: "https://example.com/cancel",
  line_items: [{ price: "price_xxx", quantity: 1 }],
  mode: "subscription"
}
checkout_params[:client_reference_id] = referral_id if referral_id.present?
checkout_params[:metadata] = referral_metadata if referral_metadata.present?
if checkout_params[:mode] == "payment"
  checkout_params[:payment_intent_data] = { metadata: referral_metadata } if referral_metadata.present?
elsif checkout_params[:mode] == "subscription"
  checkout_params[:subscription_data] = { metadata: referral_metadata } if referral_metadata.present?
end

Do not use the public ?via token as client_reference_id. Send Stripe the generated referral ID that the tracking script creates.

Affiliate link parameter

Affiliate links carry the affiliate’s public token in the via query parameter, for example https://yoursite.com/pricing?via=abc123. The script turns that token into a generated referral ID. Only the generated referral ID goes to Stripe.

Browser values the script exposes

window.AffiliateBase.referral
window.affiliatebase_referral

Browser state exists only in the visitor’s browser. Server-side Stripe code cannot read window.AffiliateBase unless the page first submits the referral value.

Keep checkout usable if the tracker fails to load, is blocked, or times out. If the current tracking attempt produces no referral, continue without attribution. Never block the purchase to wait indefinitely.

To link a signup email to the referral:

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

This records a lead, not revenue. For purchase attribution, pass the generated referral ID to Stripe; verified webhooks create the sale and commission. See the tracking reference for readiness and result handling.