> ## Documentation Index
> Fetch the complete documentation index at: https://developers.referralful.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Go from zero to tracking referrals and paying affiliates in a few minutes.
This guide gets a working affiliate program live: track referral clicks, attribute sales
(with or without Stripe), and read the commissions you owe.
In your dashboard, open **Developers → API keys**
(referralful.com/dashboard/developers)
and create one. The secret is shown once. See [Authentication](/authentication) for how to
send it.
Drop this into the `` of every page on your site. It records referral clicks and
exposes the referral id as `window.AffID.referral`:
```html theme={null}
```
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.
Tell Referralful which affiliate to credit when a customer pays.
Pass the captured referral as `client_reference_id` on the Checkout Session:
```js theme={null}
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:
```bash theme={null}
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](/report-conversions) for renewals, refunds, and attribution by
email or coupon.
Let people join through your signup page, or create them via the API:
```bash theme={null}
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.
Make a test purchase through an affiliate link, then read the data back:
```bash theme={null}
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":
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.
`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.
`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.
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](/switch-from-rewardful).