Ambassly
Sign inStart trial

Install the Ambassly Tracking Snippet

Install the Ambassly tracking snippet by adding https://ambassly.com/a.js to the pages where referrals land, then pass the captured referral code into Stripe Checkout. The script stores ?via= or ?ref= in a first-party cookie and localStorage so your checkout code can read the current referral.

Add this script to every public page where an affiliate referral may land. Put it in the <head> or just before </body>.

<script
  src="https://ambassly.com/a.js"
  data-ambassly="COMPANY_PUBLIC_ID"
  async
></script>

Replace COMPANY_PUBLIC_ID with the company public ID shown in Ambassly.

What the script records

When someone lands on your site with a referral URL like this:

https://example.com/pricing?via=CREATOR123

Ambassly reads ?via=CREATOR123, stores the referral in a first-party cookie named ambassly_ref, and mirrors it in localStorage.

Ambassly also accepts ?ref=:

https://example.com/pricing?ref=CREATOR123

The stored value contains:

{
  "code": "CREATOR123",
  "link": "https://example.com/pricing?via=CREATOR123",
  "ts": "2026-07-06T12:00:00.000Z"
}

The cookie is set for 60 days with SameSite=Lax. If a visitor clicks a different Ambassly referral link before buying, the newer click wins.

Your checkout code should read the current referral and pass the code into Stripe as client_reference_id and/or metadata.ambassly.

Read the current referral

After the script loads, it exposes:

window.Ambassly.getReferral();

Example:

<button id="buy">Buy now</button>

<script>
  document.getElementById("buy").addEventListener("click", async () => {
    const referral = window.Ambassly?.getReferral?.();

    const response = await fetch("/create-checkout-session", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        ambassly: referral?.code ?? null
      })
    });

    const { url } = await response.json();
    window.location.href = url;
  });
</script>

Safari ITP note

Ambassly uses a first-party cookie because it is the least invasive way to remember a referral on your own domain. Safari's Intelligent Tracking Prevention can cap client-set cookies to about 7 days in common referral flows.

That means a visitor who clicks an affiliate link in Safari and waits longer than Safari allows may lose client-side attribution before checkout.

The durable fix is to pass the referral code server-side as soon as you see it, then attach it to the eventual Stripe Checkout Session from your own database or session. The MVP tracking snippet still works client-side, but this Safari limit is real and should be planned for if your buyers have long consideration windows.

Test your install

  1. Open a private browser window.
  2. Visit a page on your site with a test code:
https://example.com/pricing?via=TESTCODE
  1. Open the browser console and run:
window.Ambassly.getReferral();

You should see an object whose code is TESTCODE.

  1. Confirm the first-party cookie exists:
document.cookie
  .split("; ")
  .find((cookie) => cookie.startsWith("ambassly_ref="));

  1. Start a test checkout and confirm your server sends the code to Stripe as client_reference_id and/or metadata.ambassly.

  2. In Stripe test mode, complete the checkout and let Stripe send checkout.session.completed to:

https://ambassly.com/api/hook/COMPANY_PUBLIC_ID

Ambassly resolves the code from client_reference_id or metadata.ambassly.