Ambassly

Published · Last updated

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 into Stripe Checkout. The script stores ?via= or ?ref= (and optional ?via_link=) 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&via_link=youtube-auth

Ambassly reads ?via=CREATOR123 and optional ?via_link=youtube-auth, 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": "youtube-auth",
  "ts": 1720270000000
}
  • code — affiliate referral code (?via= / ?ref=)
  • link — opaque per-content link token (?via_link=), or null if absent
  • ts — click timestamp as epoch milliseconds (Date.now())

The cookie is set for the program's cookie window (fetched from tracking config when available; otherwise 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:

  • client_reference_id and/or metadata.ambassly — the code
  • metadata.ambassly_link — the link token
  • metadata.ambassly_ts — the timestamp as a string

Read the current referral

After the script loads, it exposes:

window.Ambassly.getReferral(); // { code, link, ts } | null
window.Ambassly.getCode();     // code string | null
window.Ambassly.getLink();     // link token | null

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,
        ambassly_link: referral?.link ?? null,
        ambassly_ts: referral?.ts != null ? String(referral.ts) : null
      })
    });

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

On the server, create the Checkout Session with those fields as Stripe metadata keys ambassly, ambassly_link, and ambassly_ts (see Stripe Checkout).

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 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&via_link=test-link
  1. Open the browser console and run:
window.Ambassly.getReferral();
// → { code: "TESTCODE", link: "test-link", ts: <number> }
window.Ambassly.getLink();
// → "test-link"

You should see an object whose code is TESTCODE and link is the via_link token.

  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 to Stripe:
  • client_reference_id and/or metadata.ambassly (code)
  • metadata.ambassly_link (link token)
  • metadata.ambassly_ts (timestamp string)
  1. 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, the link from metadata.ambassly_link, and the click time from metadata.ambassly_ts.