Stripe Session API

If you’ve built your own Stripe checkout in your own app — you call Stripe from your backend to create a Checkout Session — this is the most accurate way to track referrals in Referly. You pass the referral identifier straight into the session you’re already creating, so attribution never depends on guessing who the buyer was. It’s the method Referly recommends when you have a developer available. It takes about 30 minutes end to end, and needs one small change in your frontend and one in your backend.

Not building your own checkout? Use Stripe Payment Links, the Stripe Pricing Table, or the Stripe Buy Button instead — those need no backend code.

What this method tracks

Once it’s set up, Referly follows a referred customer from the first click all the way through renewals and refunds.

What happens	Tracked	Notes
Someone clicks a referral link	Yes	Recorded by the tracking script, before Stripe is involved at all
A visitor becomes a referral at checkout	Yes	The referral appears as soon as the Checkout Session completes
A visitor becomes a referral at sign-up, before paying	Yes, with an extra step	See track sign-ups before payment
A free trial starts	Yes	The referral is created with the plan name. No commission is earned yet — there’s no payment
The first payment	Yes	The sale, the amount, the products, and the commission all land together
Subscription renewals	Yes	Every recurring payment creates a new sale and a new commission
One-off payments	Yes	Same as a subscription’s first payment
Plan changes and upgrades	Yes	The new amount is used for the next commission
Multiple currencies	Yes	Converted into your program’s currency automatically
Products bought	Yes	Used for product-based commissions
Tax and shipping	Yes	Captured separately, and excluded from the commission if you’ve turned that on in Settings then Program Details
Refunds and partial refunds	Yes	The matching reward is voided — see refunds
Cancellations	Yes	The referral is updated when the subscription ends
A purchase made with an affiliate’s promo code	Yes	Promo codes win over links — see what wins when both are present

What it can’t track

Be honest with yourself about these before you launch — every one of them shows up as an unattributed sale, not as an error.

A checkout you create without the identifier. If the value is missing when the session is created, there’s nothing to attribute. Sessions created by hand in the Stripe Dashboard fall into this group.
A buyer who switches devices. Someone who clicks the link on their phone and pays on their laptop can’t be connected — the referral is remembered in the browser that clicked.
A buyer whose browser blocked the script, or who cleared their cookies and site data between clicking and buying.
A purchase after the cookie window closed. Your program’s cookie duration decides how long a click stays valid. See tracking methods.
Payments taken outside Stripe. Bank transfers or invoices you settle elsewhere never reach Referly. Add those with add a sale.
Live payments while you’re connected in test mode, and test payments while you’re connected in live mode. Referly deliberately ignores the mismatched ones.

Before you start

A Stripe account you can log into as an administrator

You’ll authorize Referly from inside Stripe, so you need permission to connect apps to the account.

Access to your site's code

You need to be able to add a script tag to your pages and change the code that creates the Checkout Session.

Your Referly program set up

Your commission plan should exist before the first sale arrives, so rewards are calculated correctly. See affiliate program setup.

Step 1: Install the tracking script

The tracking script is what records clicks and remembers which affiliate sent each visitor. Nothing else works without it. Open Integrations from the left sidebar, find the Stripe Session API card, and select it. The guide that opens has your script already filled in with your program’s ID. Copy that snippet and paste it into the head section of every page on your site — including your pricing page and your checkout page. It looks like this:

<script
  src="https://referly.so/affiliate-tracker.js"
  data-affiliate
  data-program-id="YOUR_PROGRAM_ID"
  async>
</script>

Copy the snippet from your dashboard rather than from this page. Your program ID is unique, and programs run by an agency load the script from a different address.

If you manage your site’s tags through Google Tag Manager, the same guide has a Tag Manager version of the snippet. Add it as a Custom HTML tag that fires on all pages.

<script>
  var pushLap = document.createElement('script');
  pushLap.src = "https://referly.so/affiliate-tracker.js";
  pushLap.setAttribute('data-affiliate', '');
  pushLap.setAttribute('data-program-id', 'YOUR_PROGRAM_ID');
  document.head.appendChild(pushLap);
</script>

Check that clicks are being recorded

Visit your own site with a referral link — for example your-domain.com?ref=TESTCODE, using the code of a real affiliate in your program. Then open Analytics in the left sidebar and confirm the click shows up. If it doesn’t, the script isn’t loading, and there’s no point continuing until it does. See installing the snippet for help.

Step 2: Connect your Stripe account

Connecting Stripe is what lets Referly hear about payments. You don’t create API keys and you don’t set up a webhook endpoint by hand — you authorize Referly’s app from inside Stripe, and everything is wired up for you.

Open the connect dialog

On the Integrations page, select Connect Integration at the top right, then choose Stripe from the list.

Choose live or test

Select Connect Stripe Account to connect your real account, or Connect Test Mode to connect a sandbox first. Most people connect test mode first, check everything works, then disconnect and reconnect in live mode.

Authorize Referly in Stripe

A Stripe page opens in a new tab. Sign in if you’re asked to, pick the account you want to connect from the account picker at the top, and confirm. Stripe’s own walkthrough of this screen is in their connected accounts documentation.If you’re connecting test mode, make sure the account picker is showing a sandbox before you confirm. Stripe explains how sandboxes work in their test mode guide.

Confirm the connection

You’re sent back to Referly. The Stripe panel now shows a green Connected badge with your account name, or a yellow Test Mode badge if you connected a sandbox.

The badge colour matters. While the yellow Test Mode badge is showing, Referly processes test payments and ignores real ones. While the green Connected badge is showing, it’s the other way round. This is the single most common reason a working setup appears to record nothing.

Step 3: Read the referral identifier in your frontend

Once the script from Step 1 is on the page, it makes the referral identifier available to the rest of your frontend code as window.affiliateId. There’s a timing detail that matters. When someone lands with a referral link, the script first sets window.affiliateId to the affiliate’s code, then swaps it for a numeric click ID as soon as it has registered the click with Referly. Both values work for attribution, but only the numeric click ID connects the sale to the exact click, which is what makes your click-to-sale reporting accurate. So read the value at the moment the customer starts checkout, not when the page first loads. If you need to know the instant it’s ready, listen for the affiliate_id_ready event:

window.addEventListener("affiliate_id_ready", (event) => {
  // event.detail.clickId is the numeric click ID
  // event.detail.ref is the affiliate's code
  console.log(event.detail);
});

For most checkouts, reading it inside your button handler is enough:

async function startCheckout(priceId) {
  const response = await fetch("/api/create-checkout-session", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      priceId,
      referralId: window.affiliateId ?? null,
    }),
  });

  const { url } = await response.json();
  window.location.href = url;
}

window.affiliateId is empty for visitors who didn’t arrive through a referral link. That’s normal — send null and Referly records the sale without an affiliate.

Step 4: Attach the identifier to the Checkout Session

In your backend, put the value you just received onto the Checkout Session. Referly reads it from any of these three places, so pick whichever suits your code:

Where you put it	When to use it
`client_reference_id`	The simplest option, and the one to use if you’re not already using this field for something else. Stripe allows up to 200 characters here
`metadata.pushLapAffiliateId`	Use this if `client_reference_id` is already carrying your own cart or user ID
`metadata.affiliateId`	Also accepted, for compatibility with older setups

Using client_reference_id

const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: "price_1234", quantity: 1 }],
  success_url: "https://your-domain.com/success",
  cancel_url: "https://your-domain.com/pricing",
  client_reference_id: referralId,
});

session = stripe.checkout.Session.create(
    mode="subscription",
    line_items=[{"price": "price_1234", "quantity": 1}],
    success_url="https://your-domain.com/success",
    cancel_url="https://your-domain.com/pricing",
    client_reference_id=referral_id,
)

$session = $stripe->checkout->sessions->create([
  'mode' => 'subscription',
  'line_items' => [['price' => 'price_1234', 'quantity' => 1]],
  'success_url' => 'https://your-domain.com/success',
  'cancel_url' => 'https://your-domain.com/pricing',
  'client_reference_id' => $referralId,
]);

session = Stripe::Checkout::Session.create({
  mode: 'subscription',
  line_items: [{ price: 'price_1234', quantity: 1 }],
  success_url: 'https://your-domain.com/success',
  cancel_url: 'https://your-domain.com/pricing',
  client_reference_id: referral_id,
})

Using metadata instead

const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: "price_1234", quantity: 1 }],
  success_url: "https://your-domain.com/success",
  cancel_url: "https://your-domain.com/pricing",
  metadata: {
    pushLapAffiliateId: referralId,
  },
});

session = stripe.checkout.Session.create(
    mode="subscription",
    line_items=[{"price": "price_1234", "quantity": 1}],
    success_url="https://your-domain.com/success",
    cancel_url="https://your-domain.com/pricing",
    metadata={"pushLapAffiliateId": referral_id},
)

$session = $stripe->checkout->sessions->create([
  'mode' => 'subscription',
  'line_items' => [['price' => 'price_1234', 'quantity' => 1]],
  'success_url' => 'https://your-domain.com/success',
  'cancel_url' => 'https://your-domain.com/pricing',
  'metadata' => ['pushLapAffiliateId' => $referralId],
]);

session = Stripe::Checkout::Session.create({
  mode: 'subscription',
  line_items: [{ price: 'price_1234', quantity: 1 }],
  success_url: 'https://your-domain.com/success',
  cancel_url: 'https://your-domain.com/pricing',
  metadata: { pushLapAffiliateId: referral_id },
})

Send the field only when you actually have a value. Stripe rejects a metadata value longer than 500 characters and a client_reference_id longer than 200, and an empty string is treated as no referral. Stripe’s full rules are in their Create a Session reference and their metadata guide.

Recommended for subscriptions

For a subscription, also copy the identifier onto the subscription itself. Referly reads it when the subscription is created, which means the referral is recorded even in the rare cases where the Checkout Session event doesn’t reach it first.

const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: "price_1234", quantity: 1 }],
  success_url: "https://your-domain.com/success",
  cancel_url: "https://your-domain.com/pricing",
  client_reference_id: referralId,
  subscription_data: {
    metadata: {
      pushLapAffiliateId: referralId,
    },
  },
});

How free trials behave

If your plan starts with a free trial, the subscription is created but no money moves. Referly records the referral straight away, with the plan name and an Active status, and no reward yet. When the trial ends and the first payment succeeds, the sale and the commission are created then. This is usually what you want: affiliates see the trial as progress, and only get paid when it converts. If you’d rather hold rewards even longer, use the holding period.

Track sign-ups before payment

By default the referral appears when checkout completes. If you want it to appear the moment someone signs up — before they’ve paid anything — create the Stripe Customer yourself at sign-up and put the identifier in the customer’s metadata:

const customer = await stripe.customers.create({
  email: user.email,
  name: user.name,
  metadata: {
    pushLapAffiliateId: referralId,
  },
});

Then pass that customer to Checkout when they eventually buy:

const session = await stripe.checkout.sessions.create({
  customer: customer.id,
  mode: "subscription",
  line_items: [{ price: "price_1234", quantity: 1 }],
  success_url: "https://your-domain.com/success",
  cancel_url: "https://your-domain.com/pricing",
  client_reference_id: referralId,
});

The referral now shows up in Referly at sign-up, and the sale attaches to it later. Keep the identifier on the session too — it costs nothing and covers you if the customer was created some other way.

What wins when both are present

Sometimes more than one signal points at an affiliate. Referly resolves it in this order:

An affiliate’s promo code used at checkout. If the Stripe promotion code on the order belongs to one of your affiliates, that affiliate gets the sale, even if the click came from someone else. See coupons and promo codes.
The identifier you passed on the session. The click ID or affiliate code from Steps 3 and 4.
The customer’s email matching an existing referral. This is what makes renewals work: a renewal payment carries no click ID, so Referly matches the email to the referral created at the first purchase and pays the same affiliate again.

Point 3 is why the email matters. If a customer’s email in Stripe changes between the first payment and a renewal, the renewal won’t find the original referral and the commission won’t be paid.

Step 5: Test the whole flow

Test before you send a single affiliate link out. Do it with your Stripe connection showing the yellow Test Mode badge.

Switch Stripe to a sandbox

In the Stripe Dashboard, use the account picker at the top to switch into a sandbox. Point your app at your test API keys — Stripe’s API keys guide explains where to find them.

Visit your site through a referral link

Open your site with a real affiliate’s link, for example your-domain.com?ref=THEIRCODE. Use a private window so you start clean.

Check the identifier is there

Open your browser’s developer console and type window.affiliateId. You should get a value back. If it’s empty, go back to Step 1 — the script isn’t running.

Buy something with a test card

Go through your own checkout and pay with Stripe’s test card 4242 4242 4242 4242, any future expiry date, and any three-digit security code. The full list is in Stripe’s testing guide.

Confirm it in Stripe

In the Stripe Dashboard, open the payment and check the Checkout Session carries your value in Client reference ID or in metadata. If it isn’t there, the problem is in your backend code, not in Referly.

Confirm it in Referly

Open Referrals in the left sidebar. The customer should be listed against the right affiliate, with the plan name filled in. Then open Rewards — the commission for the payment should be there.

When the referral shows the right affiliate and the reward shows the right amount, your integration is working. Repeat the test once in live mode with a small real payment you refund afterwards — the refund should void the reward.

Go live

When your test passes:

On the Integrations page, open the Stripe panel and select Disconnect.
Select Connect Stripe Account and authorize your live Stripe account.
Confirm the badge is now green and reads Connected.
Deploy your app with your live Stripe keys.

Disconnecting and reconnecting does not delete referrals or rewards you’ve already recorded. But do leave test data behind — referrals created in test mode stay in your dashboard, so delete them before you launch if you don’t want them in your reports.

Troubleshooting

The sale is in Referly but no affiliate is attached

The identifier didn’t reach Stripe. Open the Checkout Session in the Stripe Dashboard and look for Client reference ID or your metadata key. If it’s empty, your frontend read window.affiliateId before the script had set it, or the value wasn’t passed through to your backend. Log the value at the moment you create the session and check what you’re getting.

Nothing appears in Referly at all

Nine times out of ten this is the test-mode mismatch. Check the badge on the Stripe panel: a yellow Test Mode badge means live payments are ignored, and a green Connected badge means test payments are ignored. Reconnect in the mode you’re actually testing in.If the badge is right, confirm the payment succeeded in Stripe — an incomplete or failed payment never creates a sale.

The referral appeared but there's no reward

A referral with no reward is normal for a free trial, or for a checkout that didn’t take a payment yet. The reward is created when money actually moves. If a payment did succeed and there’s still no reward, check that the affiliate is on a commission plan that covers the product they sold.

The wrong affiliate got the sale

Check whether a promo code was used. An affiliate’s promo code takes priority over the click, so a customer who clicked one affiliate’s link but typed another affiliate’s code at checkout is credited to the code owner. You can move the sale by changing the referral’s affiliate.

Renewals aren't paying commission

Renewals are matched by the customer’s email address. Compare the email on the Stripe customer with the email on the referral in Referly — if they differ, the link is broken. This usually happens when a customer changes their email in Stripe, or when the first purchase was made as a guest with a different address.

The sale showed up late

If a payment arrives before Referly has finished creating the referral, the payment is held and retried a few minutes later rather than dropped. Wait about ten minutes before assuming a sale is missing.

Stripe integration overview

Every way to connect Stripe, and which one fits you.

Stripe Payment Links

Track referrals without writing any backend code.

Tracking methods

Set your cookie duration and how clicks are attributed.

Refunds

What happens to a reward when a Stripe payment is refunded.

Getting started

Managing your program

Engaging affiliates

Gamification

Growth

Program settings

Integrations

Billing and plans

For agencies

For affiliates

Stripe Session API

What this method tracks

What it can’t track

Before you start

Step 1: Install the tracking script

Check that clicks are being recorded

Step 2: Connect your Stripe account

Step 3: Read the referral identifier in your frontend

Step 4: Attach the identifier to the Checkout Session

Using client_reference_id

Using metadata instead

Recommended for subscriptions

How free trials behave

Track sign-ups before payment

What wins when both are present

Step 5: Test the whole flow

Go live

Troubleshooting

Stripe integration overview

Stripe Payment Links

Tracking methods

Refunds

​What this method tracks

​What it can’t track

​Before you start

​Step 1: Install the tracking script

​Check that clicks are being recorded

​Step 2: Connect your Stripe account

​Step 3: Read the referral identifier in your frontend

​Step 4: Attach the identifier to the Checkout Session

​Using client_reference_id

​Using metadata instead

​Recommended for subscriptions

​How free trials behave

​Track sign-ups before payment

​What wins when both are present

​Step 5: Test the whole flow

​Go live

​Troubleshooting

​Related

Stripe integration overview

Stripe Payment Links

Tracking methods

Refunds

What this method tracks

What it can’t track

Before you start

Step 1: Install the tracking script

Check that clicks are being recorded

Step 2: Connect your Stripe account

Step 3: Read the referral identifier in your frontend

Step 4: Attach the identifier to the Checkout Session

Using client_reference_id

Using metadata instead

Recommended for subscriptions

How free trials behave

Track sign-ups before payment

What wins when both are present

Step 5: Test the whole flow

Go live

Troubleshooting

Related