Quickstart

Create a programCopy Anchor Link

In the dashboard, open Program builder and choose a template. Give and get is a good default: the friend gets a discount, and the referrer gets credit when the friend pays.

Copy the program ID from the page header. It looks like prog_8Hq2LmN4.

Install the SDKCopy Anchor Link

npm install @referral-api/js

Add your test secret key to your environment:

REFERRAL_API_KEY=sk_test_51Hx...

Enroll a referrerCopy Anchor Link

Create a referrer for one of your existing customers. The response includes their share link.

import { ReferralClient } from '@referral-api/js';

const client = new ReferralClient({ apiKey: process.env.REFERRAL_API_KEY! });

const referrer = await client.referrers.create({
  programId: 'prog_8Hq2LmN4',
  externalId: 'user_1042', 
  email: 'maya@example.com',
});

console.log(referrer.shareUrl); // https://acme.example/?ref=MAYA-20

Track the signup and paymentCopy Anchor Link

When the friend creates an account, send the signup with the referral code. When they pay, send the payment.

await client.events.signup({
  externalId: 'user_2088',
  email: 'sam@example.com',
  referralCode: 'MAYA-20',
});

await client.events.payment({
  externalId: 'user_2088',
  paymentId: 'in_1PqR2s',
  amount: 4900, // in cents
  currency: 'usd',
});

Fast-forward the hold periodCopy Anchor Link

Rewards wait for the refund window before they unlock. In test mode you can skip ahead:

await client.testClock.advance({ days: 30 });

Open Rewards in the dashboard. Maya's $20 credit is now unlocked and ready to pay.