# Create a campaign
Source: https://developers.referralful.com/api-reference/create-a-campaign
/openapi.json post /campaigns
# Create an affiliate
Source: https://developers.referralful.com/api-reference/create-an-affiliate
/openapi.json post /affiliates
# Create an affiliate coupon
Source: https://developers.referralful.com/api-reference/create-an-affiliate-coupon
/openapi.json post /affiliate_coupons
# Create an affiliate link
Source: https://developers.referralful.com/api-reference/create-an-affiliate-link
/openapi.json post /affiliate_links
# List affiliate coupons
Source: https://developers.referralful.com/api-reference/list-affiliate-coupons
/openapi.json get /affiliate_coupons
# List affiliate links
Source: https://developers.referralful.com/api-reference/list-affiliate-links
/openapi.json get /affiliate_links
# List affiliates
Source: https://developers.referralful.com/api-reference/list-affiliates
/openapi.json get /affiliates
# List campaigns
Source: https://developers.referralful.com/api-reference/list-campaigns
/openapi.json get /campaigns
# List commissions
Source: https://developers.referralful.com/api-reference/list-commissions
/openapi.json get /commissions
# List payouts
Source: https://developers.referralful.com/api-reference/list-payouts
/openapi.json get /payouts
# List referrals
Source: https://developers.referralful.com/api-reference/list-referrals
/openapi.json get /referrals
# Mark a payout as paid
Source: https://developers.referralful.com/api-reference/mark-a-payout-as-paid
/openapi.json post /payouts/{id}/pay
# Report a conversion (no Stripe)
Source: https://developers.referralful.com/api-reference/report-a-conversion-no-stripe
/openapi.json post /conversions
Record a sale from any billing system and create the affiliate commission. Provide at least one of referral_id, email, or coupon.
# Retrieve a campaign
Source: https://developers.referralful.com/api-reference/retrieve-a-campaign
/openapi.json get /campaigns/{id}
# Retrieve a commission
Source: https://developers.referralful.com/api-reference/retrieve-a-commission
/openapi.json get /commissions/{id}
# Retrieve a payout
Source: https://developers.referralful.com/api-reference/retrieve-a-payout
/openapi.json get /payouts/{id}
# Retrieve an affiliate
Source: https://developers.referralful.com/api-reference/retrieve-an-affiliate
/openapi.json get /affiliates/{id}
# Update a campaign
Source: https://developers.referralful.com/api-reference/update-a-campaign
/openapi.json put /campaigns/{id}
# Update a commission
Source: https://developers.referralful.com/api-reference/update-a-commission
/openapi.json put /commissions/{id}
# Update an affiliate
Source: https://developers.referralful.com/api-reference/update-an-affiliate
/openapi.json put /affiliates/{id}
# Void a commission
Source: https://developers.referralful.com/api-reference/void-a-commission
/openapi.json delete /commissions/{id}
# Attribution methods
Source: https://developers.referralful.com/attribution
How Referralful credits the right affiliate, including setups where the marketing site and app are on different domains.
Referralful credits an affiliate using whichever signal it can find at the time of the sale.
Pick the method that matches how your site and billing are set up.
## Quick guide
| Method | Needs the snippet? | Works across separate domains? |
| -------------------------- | ----------------------- | ------------------------------------------------ |
| **Referral link (cookie)** | Yes | Same registrable domain only (apex + subdomains) |
| **Pass the referral id** | Capture only | Yes — any domains |
| **Coupon code** | No | Yes — any domains |
| **Customer email** | Yes (to track the lead) | Same registrable domain only |
## 1. Referral link (cookie) — the default
A visitor lands on `yourbrand.com/?via=token`. The snippet stores the referral in a cookie on
your **registrable domain** (`.yourbrand.com`), so it is shared across the apex and every
subdomain automatically — `yourbrand.com`, `www.yourbrand.com`, and `app.yourbrand.com` all
see it. Each page that starts checkout needs the snippet loaded so `window.AffID.referral` is
available.
The cookie is shared across **subdomains of one registrable domain**. If your marketing site
and app are on **completely different domains** (e.g. `brand-marketing.com` and `brandapp.io`),
the cookie cannot bridge them — use method 2 or 3 below.
## 2. Pass the referral id (separate domains)
Capture `window.AffID.referral` on the landing page, carry it with the user (store it on their
account, or pass it through your signup URL), and send it as `referral_id` when they pay:
```bash theme={null}
curl https://api.referralful.com/v1/conversions \
-u rfl_live_your_secret: \
-H "Content-Type: application/json" \
-d '{ "referral_id": "ref_abc123", "amount_cents": 4900, "external_id": "invoice_12345" }'
```
This works no matter how many domains are involved, because you carry the id yourself.
## 3. Coupon codes (cookieless)
Give each affiliate a promo code. When a customer uses it, the sale is attributed by the code —
no link, no cookie, no snippet required. This is the most robust option for fully separate
domains or sites you can't add JavaScript to.
Assign a code to an affiliate:
```bash theme={null}
curl https://api.referralful.com/v1/affiliate_coupons \
-u rfl_live_your_secret: \
-H "Content-Type: application/json" \
-d '{ "affiliate_id": "aff_123", "token": "ALEX20" }'
```
Then:
* **Stripe** — when the customer applies the coupon (or promotion code) at Checkout, Referralful
reads it from the webhook and credits the affiliate automatically.
* **Any other billing** — pass the code as `coupon` when reporting the sale:
```bash theme={null}
curl https://api.referralful.com/v1/conversions \
-u rfl_live_your_secret: \
-d '{ "coupon": "ALEX20", "amount_cents": 4900, "external_id": "invoice_12345" }'
```
## 4. Customer email
If the visitor was tracked as a lead (snippet on the marketing site) and later pays, Referralful
can match the sale by the customer's email. Pass `email` to `/v1/conversions`, or it resolves
automatically for Stripe. This needs the lead to have been tracked first, so it shares the
same-domain limitation as the cookie.
# Authentication
Source: https://developers.referralful.com/authentication
Authenticate with HTTP Basic auth using your API secret as the username.
The API uses **HTTP Basic authentication**. Pass your API secret as the username and
leave the password empty. This is the same scheme Rewardful uses, so existing clients
work without changes.
## Get your API key
Create a key in your dashboard at **Developers → API keys**
(referralful.com/dashboard/developers).
The secret is shown once. Keys look like `rfl_live_…` and are tied to one program.
Treat your secret like a password. It grants full access to your program's data. If a
key leaks, revoke it in the dashboard and create a new one.
## Send the key
With `curl`, pass the secret to `-u` followed by a colon (empty password):
```bash theme={null}
curl https://api.referralful.com/v1/affiliates \
-u rfl_live_your_secret_here:
```
Or set the `Authorization` header yourself (base64 of `secret:`):
```bash theme={null}
curl https://api.referralful.com/v1/affiliates \
-H "Authorization: Basic $(printf 'rfl_live_your_secret_here:' | base64)"
```
A `Bearer` token is also accepted as a convenience:
```bash theme={null}
curl https://api.referralful.com/v1/affiliates \
-H "Authorization: Bearer rfl_live_your_secret_here"
```
## Errors
A missing or invalid key returns `401`:
```json theme={null}
{ "error": "Invalid API key." }
```
# Errors
Source: https://developers.referralful.com/errors
Standard HTTP status codes with a JSON error message.
The API uses conventional HTTP status codes. Errors return a JSON body with an `error`
string.
```json theme={null}
{ "error": "email is required." }
```
| Status | Meaning |
| ------ | ---------------------------------------------------- |
| `200` | Success |
| `201` | Resource created |
| `401` | Missing or invalid API key |
| `404` | Resource not found |
| `422` | Validation failed (e.g. a required field is missing) |
| `500` | Something went wrong on our end |
# Introduction
Source: https://developers.referralful.com/introduction
The Referralful REST API — manage affiliates, referrals, commissions, and report conversions without Stripe.
The Referralful REST API lets you manage your affiliate program programmatically:
create and update affiliates, read referrals and commissions, mark payouts as paid,
and report conversions from any billing system, not just Stripe.
## Base URL
```
https://api.referralful.com/v1
```
All requests are made over HTTPS. Responses are JSON.
## Built to be Rewardful-compatible
If you already use Rewardful, switching is mostly a find-and-replace. The endpoints,
object shapes, field names, authentication, and pagination match Rewardful's REST API,
so you change the base URL and your API key, and your existing code keeps working.
See exactly what changes (the host and the key) and what stays the same (everything else).
## Don't use Stripe?
Stripe merchants get conversions tracked automatically. If you bill another way, report
each sale with a single API call and Referralful runs it through the same commission
engine.
Send a sale from your backend, attribute it to an affiliate, and create the commission.
## Resources
| Resource | Description |
| ----------------- | ------------------------------------------------------ |
| Campaigns | Programs with their commission and cookie rules |
| Affiliates | The people promoting you, with their links and coupons |
| Affiliate links | Tracking links (tokens) for an affiliate |
| Affiliate coupons | Promo codes tied to an affiliate |
| Referrals | Visitors, leads, and conversions an affiliate drove |
| Commissions | Amounts owed to affiliates per sale |
| Payouts | Batches of commissions paid out |
| Conversions | Report a sale from any billing system |
# Pagination
Source: https://developers.referralful.com/pagination
List endpoints are paginated with page and limit.
List endpoints return a `pagination` object alongside `data`. Control the page with
`page` (1-based) and the page size with `limit` (default `25`, max `100`).
```bash theme={null}
curl "https://api.referralful.com/v1/affiliates?page=2&limit=50" \
-u rfl_live_your_secret:
```
```json theme={null}
{
"pagination": {
"previous_page": 1,
"current_page": 2,
"next_page": 3,
"count": 50,
"limit": 50,
"total_pages": 4,
"total_count": 180
},
"data": [ ]
}
```
When `next_page` is `null`, you've reached the last page.
# Quickstart
Source: https://developers.referralful.com/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).
# Report conversions (no Stripe)
Source: https://developers.referralful.com/report-conversions
Record a sale from any billing system and create the affiliate commission.
If you bill outside Stripe (Paddle, Lemon Squeezy, Chargebee, your own billing, manual
invoices), report each sale with one API call. Referralful runs it through the same
commission engine Stripe sales use.
## How attribution works
When a visitor arrives through an affiliate link, our tracking snippet stores a referral
and exposes its id as `window.AffID.referral`. Capture that id at signup or checkout and
send it back when the customer pays. You can also attribute by the customer's email (if
they were tracked as a lead) or by an affiliate's coupon code.
## Report a sale
```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"
}'
```
Provide at least one of `referral_id`, `email`, or `coupon` to attribute the sale.
### Idempotency and renewals
`external_id` makes the call safe to retry. For subscriptions, send one conversion per
charge, each with its own `external_id` (e.g. the invoice id). Recurring commissions are
created automatically as long as the campaign's commission period allows it.
### Refunds
Reversing a sale (and clawing back its commission) uses the same `external_id`. Refund
support via the API is rolling out; until then, void the commission with
`DELETE /v1/commissions/:id`.
## Response
```json theme={null}
{
"object": "conversion",
"duplicate": false,
"sale_id": "…",
"commission": {
"id": "…",
"object": "commission",
"amount": 1470,
"currency": "usd",
"state": "pending"
}
}
```
If no affiliate referral matches, you get `422` with
`{ "error": "No matching referral found for this conversion." }`.
# Switch from Rewardful
Source: https://developers.referralful.com/switch-from-rewardful
Point your existing Rewardful integration at Referralful with two changes.
The Referralful API mirrors Rewardful's REST API, so moving over is a find-and-replace,
not a rewrite.
## What changes
Replace `https://api.getrewardful.com/v1` with `https://api.referralful.com/v1`.
Swap your Rewardful API Secret for a Referralful key from
[your dashboard](https://referralful.com/dashboard/developers). Auth is the same:
HTTP Basic with the key as the username.
That's it. The paths, object shapes, field names, pagination, and error format are the
same.
## What stays the same
* **Endpoints** — `/campaigns`, `/affiliates`, `/affiliate_links`, `/affiliate_coupons`,
`/referrals`, `/commissions`, `/payouts`.
* **Object fields** — `commission_amount_cents`, `days_before_referrals_expire`,
`minimum_payout_cents`, `max_commission_period_in_months`, and the rest match.
* **Pagination** — the same `{ pagination, data }` envelope.
## Bring your data with you
Before you flip the API over, import your existing Rewardful program (campaigns,
affiliates, links, coupons, referrals, commissions, payouts) in one click from
**Dashboard → Import**. Affiliate tokens are preserved, so existing referral links keep
working.
## Example
The only diff in a typical client:
```diff theme={null}
- const BASE = "https://api.getrewardful.com/v1";
- const KEY = "your_rewardful_secret";
+ const BASE = "https://api.referralful.com/v1";
+ const KEY = "rfl_live_your_referralful_key";
```