Quickstart

This guide gets a working affiliate program live: track referral clicks, attribute sales (with or without Stripe), and read the commissions you owe.

Create an API key

In your dashboard, open Developers → API keys (referralful.com/dashboard/developers) and create one. The secret is shown once. See Authentication for how to send it.

Add the tracking snippet

Drop this into the <head> of every page on your site. It records referral clicks and exposes the referral id as window.AffID.referral:

<script async
  src="https://cdn.jsdelivr.net/gh/mihir-kanzariya/affiliate-script@0.4/dist/aff.min.js"
  data-account="YOUR_ACCOUNT_SLUG"
  data-track-url="https://api.referralful.com"></script>

Find your exact snippet in Dashboard → Settings → Tracking snippet.

Separate app subdomain? If your marketing site is yourbrand.com and your app or checkout is on app.yourbrand.com, add the snippet to both. The referral cookie is stored on your registrable domain (.yourbrand.com), so it is shared across every subdomain automatically — but each page that starts checkout needs the snippet loaded so window.AffID.referral is available there.

Attribute the sale

Tell Referralful which affiliate to credit when a customer pays.

Stripe
Any other billing (no Stripe)

Pass the captured referral as client_reference_id on the Checkout Session:

const session = await stripe.checkout.sessions.create({
  client_reference_id: referral, // = window.AffID.referral from the browser
});

Conversions and recurring commissions track automatically from Stripe.

It must be client_reference_id on the Checkout Session — not customer metadata, and not the Subscription. Referralful only reads client_reference_id (and, as a fallback, the email you pass to AffID.convert). The most common cause of “clicks track but conversions don’t” is the referral being sent somewhere else.

Report the sale from your backend when the customer pays:

curl https://api.referralful.com/v1/conversions \
  -u rfl_live_your_secret: \
  -H "Content-Type: application/json" \
  -d '{
    "referral_id": "the-referral-id-from-window-AffID",
    "amount_cents": 4900,
    "currency": "usd",
    "email": "customer@example.com",
    "external_id": "invoice_12345"
  }'

See Report conversions for renewals, refunds, and attribution by email or coupon.

Add affiliates

Let people join through your signup page, or create them via the API:

curl https://api.referralful.com/v1/affiliates \
  -u rfl_live_your_secret: \
  -H "Content-Type: application/json" \
  -d '{ "email": "alex@example.com", "first_name": "Alex" }'

The response includes the affiliate’s links (their tracking tokens) to share.

Verify it works

Make a test purchase through an affiliate link, then read the data back:

curl https://api.referralful.com/v1/referrals   -u rfl_live_your_secret:
curl https://api.referralful.com/v1/commissions -u rfl_live_your_secret:

You should see a referral move to conversion and a commission appear.

Make sure conversions actually track

The snippet tracking clicks is only half of it — these are the things that most often cause “clicks track but conversions don’t”:

Cover every checkout path

If customers can start a subscription from more than one place — onboarding, a pricing page, an in-app “upgrade” modal — set client_reference_id in all of them. Miss one and sales from that path won’t attribute.

Read the referral at checkout time, not page load

window.AffID.referral is available as soon as the tracking script has loaded. Read it at the moment you create the Checkout Session, not from a value captured on first render that might still be empty if the user clicked quickly.

It goes on the Session, not the customer

client_reference_id must be on the Checkout Session. Putting the referral in customer metadata or on the Subscription won’t work — Referralful doesn’t read those.

Verify it in Stripe

Open the Checkout Session in the Stripe Dashboard — client_reference_id should show your referral id. If it’s empty, the referral never reached checkout (fix the integration); if it’s set but no commission appears, check that the customer paid (a $0 trial doesn’t create a commission until the first real charge).

Free trials

A trial subscription is handled automatically — you don’t configure anything extra:

At signup: the referral is recorded as a conversion and the customer is linked to the affiliate. No commission yet (no money moved).
At the first real charge (trial end): the commission is created for the affiliate, based on the amount actually charged.
If they cancel during the trial: no charge, no commission.

Just pass client_reference_id once at checkout — Referralful handles the trial → paid transition. In your dashboard, trial subscribers show under Trials until they’re charged, then move to Conversions.

Coming from Rewardful?

Change the base URL and key, and your existing code works unchanged. See Switch from Rewardful.

Getting started

Guides

Make sure conversions actually track

Free trials

Coming from Rewardful?

​Make sure conversions actually track

​Free trials

​Coming from Rewardful?

Make sure conversions actually track

Free trials

Coming from Rewardful?