Pass the referral from your own checkout
If your code creates the Stripe Checkout Session, hand the partner's code to Stripe yourself.
The snippet adds the partner's code to Stripe Payment Links, pricing tables and buy buttons by itself. If your own server creates the Checkout Session, it cannot reach that code, so you pass it. The snippet exposes it as window.EqualRef.referral.
Step 1: send the code to your server
When the visitor clicks your buy button, send window.EqualRef.referral along with the request. It is empty when the visitor did not arrive through a partner's link.
const referral = window.EqualRef?.referral || "";
await fetch("/api/checkout", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ referral }),
});Step 2: put it on the Checkout Session
Set it as client_reference_id when you create the session. This is the normal way, and the way this product looks for first.
const session = await stripe.checkout.sessions.create({
mode: "subscription",
line_items: [{ price: PRICE_ID, quantity: 1 }],
success_url: "https://your-site.com/thanks",
client_reference_id: referral || undefined,
});Or: put it in metadata
If you cannot set client_reference_id, put the code in metadata.aft_ref on the Stripe customer or on the subscription. The product reads it from either.
const session = await stripe.checkout.sessions.create({
mode: "subscription",
line_items: [{ price: PRICE_ID, quantity: 1 }],
success_url: "https://your-site.com/thanks",
subscription_data: { metadata: { aft_ref: referral } },
});The shape of the code
Only letters, digits, dashes and underscores survive. Stripe drops any other character silently, and the product ignores a code in any other shape. Send the code exactly as the snippet gives it, up to 200 characters, and do not wrap it in anything.
The product reads the code the next time it reads your Stripe events, within five minutes. A code that matches no active partner is ignored.