R
Referral Engine

Quick Start

Get your referral program up and running in under 5 minutes.

This guide walks you through creating your first referral campaign, installing the SDK, and generating your first referral link. By the end, you'll have a working referral system.

Prerequisites

  • A Referral Engine account (sign up free)
  • A web or mobile application to integrate with
  • Node.js 18+ (for JavaScript SDK)

Step 1: Create a Campaign

  1. Log into your Referral Engine dashboard
  2. Click New Campaign
  3. Enter a name for your campaign (e.g., "Invite Friends")
  4. Choose your reward trigger:
    • Signup — Reward when referred user creates an account
    • Purchase — Reward when referred user makes a purchase
    • Custom event — Reward when you send a custom event
  5. Configure reward amounts for both referrer and referred user (or just one)
  6. Click Create Campaign
Start with "Signup" as your reward trigger for testing. You can always change it later.

Step 2: Get Your API Keys

Navigate to Settings → API Keys in your dashboard. You'll need:

  • Public Key — Used in client-side code (safe to expose)
  • Secret Key — Used in server-side code (keep this secret!)

Step 3: Install the SDK

# Using npm
npm install @referral-engine/sdk

# Using yarn
yarn add @referral-engine/sdk

# Using pnpm
pnpm add @referral-engine/sdk

Step 4: Initialize the SDK

lib/referral.tstypescript
import { ReferralEngine } from '@referral-engine/sdk'

const referral = new ReferralEngine({
  apiKey: process.env.REFERRAL_ENGINE_PUBLIC_KEY,
  campaignId: 'camp_xxxxx' // From your dashboard
})

Step 5: Generate a Referral Link

When a user wants to share their referral link, generate one for them:

components/share-button.tsxtypescript
// In your share button handler
async function getShareLink(userId: string) {
  const { url, code } = await referral.createLink({
    userId: userId,
    metadata: {
      source: 'share-button'
    }
  })
  
  return url // https://refer.yourapp.com/abc123
}

Step 6: Track Conversions

When a referred user completes your reward trigger action, track it:

api/events.tstypescript
// After user signs up
await referral.trackEvent({
  type: 'signup',
  userId: newUser.id,
  referralCode: referralCodeFromUrl // From ?ref= parameter
})

// After user makes a purchase
await referral.trackEvent({
  type: 'purchase',
  userId: user.id,
  referralCode: user.referralCode,
  metadata: {
    amount: 99.99,
    orderId: 'order_123'
  }
})
For server-side event tracking (recommended for purchases), use your Secret Key instead of the Public Key. This prevents users from spoofing events.

Step 7: Handle Rewards

When a reward is triggered, we'll send a webhook to your configured endpoint:

app/api/webhooks/referral/route.tstypescript
// In your webhook handler
export async function POST(request: Request) {
  const payload = await request.json()
  
  if (payload.type === 'reward.earned') {
    const { referrerId, referredId, rewardType, amount } = payload.data
    
    // Apply the reward in your system
    await grantCredit(referrerId, amount)
    
    // Optionally notify the user
    await sendNotification(referrerId, 
      `You earned ${amount} for referring a friend!`
    )
  }
  
  return Response.json({ received: true })
}

Test Your Integration

  1. Generate a referral link for a test user
  2. Open the link in an incognito window
  3. Complete the signup flow as the referred user
  4. Check your dashboard — you should see the conversion!

Need help?

Check out our Testing Guide for detailed instructions on testing your integration in development and staging environments.

What's Next?