Application referral integration

Capture referral clicks with the landing script, name your customers, connect signups to clicks, and send purchases from your application backend.

A referral integration has three parts: the landing script captures the referral click in the browser, your backend tells RefRef which browser created each new account, and your backend sends the facts that count, such as signups and purchases. RefRef keeps every referral record. Your application hosts no capture endpoint and stores nothing for referrals.

Start with a Sandbox Project and one signup flow.

Prepare the Project

Use a Project with an active referral Program that has a landing page URL and at least one benefit rule with published reward terms.

Backend requests use X-Api-Key with a Workspace API key of the Project's environment. A Sandbox key cannot operate on a Live Project. Keep the key in backend secret storage, never in browser code, prompts, or logs. The running API's GET /openapi describes the current request schemas.

Add the landing script

Add the script to every page where a referral link can land:

<script
  src="https://assets.refref.ai/attribution.v1.js"
  data-api-url="https://api.refref.ai"
  defer
></script>
  • data-api-url is the RefRef API of your environment.
  • data-cookie-domain is optional. By default, the cookie belongs to the domain of the page without its subdomain, so all subdomains share it: a click on www.example.com reaches a signup on app.example.com and a backend on api.example.com. Separate domains, such as example.com and example.app, do not share it. Set data-cookie-domain only to choose another domain.

A referral link goes through RefRef's redirect service, which adds refref_handoff to the landing URL. The script exchanges it with RefRef for the browser's referral handle, stores the handle in the first-party cookie refref_handle (90 days, SameSite=Lax), and removes refref_handoff from the URL. A page without refref_handoff sends no request.

A signup form can wait for capture, so that your backend sees the cookie. The script has no time limit of its own, so add one:

await Promise.race([
  window.RefRefAttribution?.capture(),
  new Promise((resolve) => setTimeout(resolve, 3000)),
]);

The promise of capture() always resolves, also when capture fails, so capture never blocks your page. A Content Security Policy must allow the Assets host in script-src and the API host in connect-src.

Safari keeps a cookie that a script writes for 7 days only. To keep it longer, your backend can set the same refref_handle cookie again in its responses, with the value that the request carries and the same attributes. Do not make it HttpOnly, and never create or change its value.

Name your customers

Name each customer with your own stable ID: { kind: "individual", externalId: "your-user-id" } for a person, or { kind: "group", externalId: "your-account-id" } for a company. RefRef does not match customers by email and stores no group membership. An optional individual actor records who acted for a group.

A trusted call that names an unknown customer creates it, so there is no separate registration call. To change a customer's ID later, use POST /v1/participants/rekey.

Connect signups to clicks

When an account is created, your backend sends the signup and the browser's handle:

await fetch("https://api.refref.ai/v1/track/events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": process.env.REFREF_API_KEY!,
  },
  body: JSON.stringify({
    projectId: process.env.REFREF_PROJECT_ID,
    type: "signup",
    participant: { kind: "individual", externalId: user.id },
    identify: { handle: cookies.get("refref_handle") },
  }),
});

Email verification, magic links, hosted login pages, webhooks, and company accounts each need a small variation. See signup tracking with any auth system.

Add sharing

The signup enrolls a new customer in the referral Program, unless its "Enroll every new customer" switch is off. The Widget enrolls a customer the first time it loads for them, and shows their sharing link. Your backend issues its short-lived Widget JWT, which names the Program. To let a customer refer without the Widget, enroll them with POST /v1/enrollments: the enrollment creates their referral code, and POST /v1/referral-codes returns it. A vanity link uses POST /v1/referral-links and needs the existing code.

Send purchases

A purchase Event carries its economic facts in purchase. RefRef derives its key from the paid invoice or order and uses paidAt as its time. A purchase carries no browser data: it uses the customer's existing referral. Send only verified billing facts from your backend. A connected billing integration, such as Stripe, sends purchases for you. Subscription renewals keep the referral of their Subscription.

An earned Reward is an accounting result. Delivering it is a separate step.

Check your integration

TestExpected result
A shares a link; B follows it in another browser and signs upB's signup has a referral from A
B buys laterThe purchase uses B's referral; no new referral
B signs in againNo second signup
An existing user follows a referral linkNo referral
You inspect the browser bundle and requestsNo API key

For tool-specific prompts and rules files, see the guides for coding agents such as Claude Code, Codex, and Cursor, and for app builders such as Lovable and v0.

On this page