Your first referral in 5 minutes

In this walkthrough you set up a test program, give a partner a link, click it, sign up in your own app, and watch Referalli credit the partner. Everything runs in test mode, so nothing touches live data. Pick the Node (Express) or Next.js section for your app; the first three steps are the same for both. For the same flow with plain HTTP, see the curl quickstart.

You need Node.js 20 or later and a Referalli account (sign in at https://referalli.com/login).

1. Get a test API key

   In the dashboard, turn on Test mode in the side bar, then open Settings → API keys and click Create API key with Full access. Copy the key (rk_test_...): it is shown once.

   export REFERALLI_API_KEY=rk_test_...

   Keep this key on your server. It never goes in a browser or an app.

2. Install the SDK and the CLI

   npm install referalli
   npm install -g @referalli/cli
   referalli login --key $REFERALLI_API_KEY

3. Create a program, a partner and a link

   Save this as setup.mjs and run node setup.mjs. It creates a program that pays 20% of every payment, a partner named Dana, and Dana's link to your app on localhost:3000:

   // setup.mjs
   import { Referalli } from 'referalli';
   
   const referalli = new Referalli(); // reads REFERALLI_API_KEY
   
   const program = await referalli.programs.create({ name: 'Acme Partners', slug: 'acme-partners' });
   await referalli.commissionRules.create({
     programId: program.id,
     config: { base: { kind: 'percent', bps: 2000 } }, // 20%
   });
   
   const partner = await referalli.partners.create({ email: 'dana@example.com', displayName: 'Dana', upsert: true });
   await referalli.programs.enrollments.create(program.id, { partnerId: partner.id });
   
   const link = await referalli.links.create({
     programId: program.id,
     partnerId: partner.id,
     destinationUrl: 'http://localhost:3000/',
   });
   const { trackingToken } = await referalli.org.retrieve();
   
   console.log(`REFERALLI_PROGRAM_ID=${program.id}`);
   console.log(`REFERALLI_TRACKING_TOKEN=${trackingToken}`);
   console.log(`Dana's link: ${link.shortUrl ?? `https://referalli.com/go/${trackingToken}/${link.code}`}`);

   Put the two printed variables in your app's environment. A click on Dana's link redirects to http://localhost:3000/?via=<code>&ref_click_id=clk_...; the next step captures those parameters.

Node (Express)

npm install express @referalli/express

// server.mjs
import express from 'express';
import { Referalli } from 'referalli';
import { attributeSignup, referalliAttribution } from '@referalli/express';

const referalli = new Referalli(); // REFERALLI_API_KEY
const app = express();

// Saves ?via= / ref_click_id into the first-party referalli_ctx cookie, and sets req.referral.
app.use(referalliAttribution({ publishableKey: process.env.REFERALLI_TRACKING_TOKEN }));
app.use(express.urlencoded({ extended: false }));

app.get('/', (req, res) => {
  res.send(`
    <h1>Acme</h1>
    <p>${req.referral?.code ? `Invited with code ${req.referral.code}` : 'No referral yet'}</p>
    <form method="post" action="/signup"><input name="email" placeholder="you@example.com"><button>Sign up</button></form>`);
});

app.post('/signup', async (req, res) => {
  const user = { id: `user_${Date.now()}`, email: req.body.email }; // your real user creation goes here
  const result = await attributeSignup(req, {
    client: referalli,
    programId: process.env.REFERALLI_PROGRAM_ID,
    customerRef: user.id, // the id your billing provider will see for this customer
    email: user.email,
  });
  res.send(result?.referral ? `Referred by partner ${result.referral.partnerId}` : 'Signed up (not referred)');
});

app.listen(3000, () => console.log('http://localhost:3000'));

node server.mjs

attributeSignup reads the cookie and calls associate with the idempotency key signup:<customerRef>, so a retried signup is attributed once. It never throws: attribution can't break your signup. A complete version with webhooks is express-webhooks in referalli-examples.

Next.js

npm install @referalli/next

Add the middleware, which saves the referral into the cookie before any page renders:

// middleware.ts
export { referalliMiddleware as middleware } from '@referalli/next/middleware';
export const config = { matcher: ['/((?!_next|api|.*\\..*).*)'] };

Then attribute the signup from a server action:

// app/page.tsx
import { Referalli } from 'referalli';
import { attributeSignup, getReferral } from '@referalli/next';

const referalli = new Referalli(); // REFERALLI_API_KEY

async function signUp(form: FormData) {
  'use server';
  const user = { id: `user_${Date.now()}`, email: String(form.get('email')) }; // your real user creation goes here
  await attributeSignup({
    client: referalli,
    programId: process.env.REFERALLI_PROGRAM_ID!,
    customerRef: user.id,
    email: user.email,
  });
}

export default async function Home() {
  const referral = await getReferral();
  return (
    <main>
      <h1>Acme</h1>
      <p>{referral?.code ? `Invited with code ${referral.code}` : 'No referral yet'}</p>
      <form action={signUp}>
        <input name="email" placeholder="you@example.com" />
        <button>Sign up</button>
      </form>
    </main>
  );
}

npm run dev

A complete app with the browser kit and a webhook route is nextjs-saas in referalli-examples; see also React and Next.js.

Click, sign up, and watch the referral arrive

1. In a second terminal, run referalli events tail.

2. Open Dana's link in your browser. You land on localhost:3000 with "Invited with code …".

3. Submit the signup form.

The terminal shows the new referral:

12:00:07  referral.created         evt_01JB...  partnerId=ptr_... referralId=ref_... status=active

The referral is also under Referrals in the dashboard (still in test mode). When this customer pays, through a connected billing provider or the generic conversion API, Dana earns 20% as a commission line.

Nothing showed up? The browser must carry the cookie from the link click to the signup, so use the same browser and host (localhost, not 127.0.0.1). Links are fraud-scored, and a click from a script or a curl user agent counts as a bot, so click the link in a real browser.

Next steps

• Receive webhooks: referalli listen --forward-to http://localhost:3000/webhooks/referalli forwards live events to your app.

• Connect your billing provider so payments earn commissions automatically.

• Set up payouts and commission rules.

• Using another language? Every SDK has the same calls.