Overview and quickstart

RefRef runs referral and partner programs for your product. It records who referred whom, decides which Events count, calculates Rewards, and delivers them or tells your product to deliver them.

What RefRef doesCopy Anchor Link

• Capture. A referral link goes through RefRef. The landing script on your site keeps a first-party handle for the browser.
• Identify. When an account is created, your backend tells RefRef which browser created it.
• Attribute. RefRef connects the account to the referrer, and keeps that referral for later purchases and renewals.
• Reward. Benefit rules in your Programs turn Events into Rewards: cash, account credit, discounts, or custom units such as free months.
• Deliver. RefRef delivers Rewards through a connected billing provider, pays cash Rewards, or sends your product a signed webhook so that it grants the Reward.
• Share. The Referral Widget shows each customer their link. Partners such as affiliates join through an invitation or an application and use the Partner app.

Integrations: Stripe, Dodo Payments, Paddle, Polar, RevenueCat, Shopify, and WooCommerce. For automations, see Zapier, Make, and Activepieces.

RefRef does not attribute installs of native mobile apps. The Widget shows sharing only, not a referral history.

Sandbox and LiveCopy Anchor Link

Each Project is a pair: a Live Project for real customers and a Sandbox Project for tests. They have different IDs, client secrets, and data. An API key belongs to one environment and reaches only its Projects. In the Sandbox, billing deliveries and payouts go through a simulated provider and move no money.

Build and test everything in the Sandbox Project first. Then repeat the configuration in the Live Project and change your keys and IDs.

QuickstartCopy Anchor Link

1. Create your Workspace and ProjectCopy Anchor Link

Sign up for RefRef. You get a Workspace. Create your first Project with its name and its website URL. RefRef creates the Live and Sandbox Projects together. See Projects.

2. Create a referral ProgramCopy Anchor Link

In the Sandbox Project, create a Program from a template. Set the landing page URL where referral links lead, and the Rewards: for example, a cash Reward for the referrer on each referee purchase. Publish the reward terms. See Programs.

3. Get your credentialsCopy Anchor Link

As an owner or admin, open the Sandbox Project. Create a Sandbox key in Developers → API keys, and copy the client secret from Developers → Secrets. The Project ID is on the Program's Install tab. Keep the key and the secret on your server.

4. Install the landing scriptCopy Anchor Link

Add the script to every page where a referral link lands:

<script
  src="https://assets.refref.ai/attribution.v1.js"
  data-api-url="https://api.refref.ai"
  defer
></script>

See Landing script and facts.

5. Send the signup with identifyCopy Anchor Link

When your backend creates an account, send the signup with 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 },
    ...(handle && { identify: { handle } }),
  }),
});

handle is the value of the refref_handle cookie. Magic links, email verification, and hosted login pages need a small variation: see signup tracking and the recipe for your auth system.

Connect a billing integration to send purchases, or send them from your backend. See Events.

6. Embed the WidgetCopy Anchor Link

Sign a short-lived Widget token for the customer and the referral Program on your backend, and load the Widget. The first time the Widget loads for a customer, RefRef enrolls the customer in the Program and creates their link. See Referral Widget.

7. Test in the SandboxCopy Anchor Link

1. Customer A opens the Widget and copies the link.
2. In another browser, open the link and sign up as customer B.
3. Make a test purchase as B.
4. In the Console, check that B has a referral from A, that the Events are decided, and that A has a Reward.
5. Check that an existing user who follows the link gets no referral, and that no API key is in your browser code.

NextCopy Anchor Link