Web

Get your test keys

In the dashboard, go to Developers → API keys and copy your test publishable key (pk_test_…). You will also use your test secret key (sk_test_…) in step 6 to simulate the referred user from your terminal — export it now:

export INVITEBASE_SECRET_KEY=sk_test_...

The _test_ prefix is what keeps everything in this guide isolated, unbilled, and free.

Create a campaign

A campaign defines what counts as a referral and what the reward is. In Campaigns → New campaign, pick the Paid subscription template. It creates a campaign whose qualification gate validates when the referred user starts a paid subscription within 14 days — tweak the events, target, or window right in the builder.

Copy the campaign ID (for example 7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15) — the SDK needs it to mint links.

Install the SDK

npm install @invitebase/js

pnpm and CDN install options, browser support, and package details are in Web setup.

Configure and identify

Call configure once at app startup with your test publishable key. The SDK starts an anonymous session immediately — attribution and tracking work before anyone logs in — and identify aliases that history onto your user once you know who they are.

import invitebase from '@invitebase/js';

invitebase.configure('pk_test_...');

// After signup/login:
invitebase.identify({ id: 'usr_123', email: 'sam@example.com' });

Use your user's stable ID from your own database — it is how Invitebase ties events, referrals, and rewards back to them.

Get a referral link

Ask for the user's link in the campaign you created. Links are unique per referrer per campaign, and repeated calls return the same link.

const link = await invitebase.getReferralLink('7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15');

console.log(link.url);  // https://mycompany.refr.link/a1b2c3
console.log(link.code); // a1b2c3

Render link.url behind your "Invite a friend" button. When a friend opens it, the redirect page records the click (the referral is created in the clicked state) and the code is persisted in a first-party cookie, so the Web SDK attaches it automatically when the friend signs up on your site.

Simulate the referred signup and qualifying event

In production the friend's browser does this for you. For the quickstart, play the friend from your terminal with your secret key. First the signup, carrying the referral code for attribution:

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "signup",
    "referred_user_id": "usr_friend_1",
    "referral_code": "a1b2c3"
  }'

The referral moves to signed_up. Now the qualifying event your campaign gates on:

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "subscription_started",
    "referred_user_id": "usr_friend_1",
    "properties": { "plan": "paid" }
  }'

You can fire the same two events without a terminal from Developers → Event simulator in the dashboard.

In your own app, this second event is one call wherever the real behavior happens:

invitebase.track('subscription_started', { plan: 'paid' });

Watch it validate

Open the dashboard Overview. Both events appear in the live feed, and under Campaigns → your campaign → Referrals the referral moves signed_up → in_progress → validated. Validated is the moment that matters: it is when fraud checks have passed, rewards fire, and (in live mode) billing counts.

Your app can react to the same moment without polling:

invitebase.on('referralStateChanged', ({ referral }) => {
  console.log(referral.id, referral.state); // 5f8e2a1d-… → validated
});