referral-program

What this skill does

# Referral Program

## Overview

A referral program turns your existing customers into an acquisition channel by rewarding them for introducing new customers. Referral apps like ReferralCandy and Referral Hero handle unique link generation, double-sided rewards (referrer and referee), fraud detection, and post-purchase email triggers without custom code. Only build a custom referral system if your tiering logic, CRM integration, or fraud rules exceed what these tools support.

## When to Use This Skill

- When building a "give $10, get $10" refer-a-friend program
- When adding tiered rewards that escalate with the number of successful referrals
- When fraud from self-referrals or multiple accounts is draining referral reward budget
- When measuring referral program CAC versus other acquisition channels
- When integrating referral tracking with post-purchase email flows in Klaviyo

## Core Instructions

### Step 1: Determine platform and choose the right referral tool

| Platform | Recommended Tool | Why |
|----------|-----------------|-----|
| **Shopify** | ReferralCandy | Purpose-built for e-commerce; auto-generates referral links per customer, handles double-sided rewards, post-purchase email trigger, and fraud detection |
| **Shopify** | Referral Hero | More flexible reward types (cash, gift cards, store credit, custom); deep Klaviyo integration for referral email flows |
| **Shopify** | Smile.io | Combines loyalty points with referral mechanics in one app — best when you want both |
| **WooCommerce** | ReferralCandy or Referral Hero | Both offer WooCommerce plugins; connect via REST API to track orders and issue rewards |
| **BigCommerce** | ReferralCandy | Available on the BigCommerce App Marketplace |
| **Custom / Headless** | Build referral tracking + reward logic | Required when platform integrations or fraud rules don't match your needs |

---

### Step 2: Platform-specific setup

---

#### Shopify

**Option A: ReferralCandy (recommended — full referral suite)**

1. Install **ReferralCandy** from the Shopify App Store
2. Connect your Shopify store — ReferralCandy automatically imports existing customers
3. Configure your reward structure:
   - Go to **ReferralCandy → Rewards → Set Rewards**
   - Choose reward type for referrer: cash via PayPal, store discount, or custom gift
   - Choose reward type for referee: discount code applied at checkout
   - Example: Referrer gets $10 store credit; referee gets $10 off their first order

4. Configure referral email timing:
   - Go to **Post-Purchase Email → Settings**
   - Set send delay to 1–3 days after purchase (customer is in the honeymoon phase)
   - Customize the email template with your brand and the referral link

5. ReferralCandy automatically:
   - Generates a unique referral link per customer
   - Tracks clicks and attributions with a 30-day cookie window
   - Detects self-referrals and blocks reward issuance
   - Sends the referee a welcome email with their discount code when they sign up via the link

6. View performance in **ReferralCandy → Analytics**:
   - Referrals sent, clicks, signups, and purchases
   - Revenue attributed to referrals
   - Top referrers (for VIP outreach)

**Option B: Referral Hero (Klaviyo-first)**

1. Install **Referral Hero** from the App Store
2. Configure in **Referral Hero → Campaigns → Create Campaign**
3. Referral Hero integrates with Klaviyo — when a referral converts, it triggers a Klaviyo flow for reward notification emails
4. Reward types include store credit (issued via Shopify discount codes), cash (PayPal), or gift cards

**Adding a referral entry point in post-purchase emails (Klaviyo):**
1. In Klaviyo, go to the **Post-Purchase flow**
2. Add an email at the 3-day step with the referral link
3. ReferralCandy and Referral Hero both provide a Klaviyo integration that injects `{{ customer.referral_link }}` as a merge tag

---

#### WooCommerce

**ReferralCandy for WooCommerce:**

1. Install the **ReferralCandy** plugin from WordPress.org or the ReferralCandy integrations page
2. Connect your WooCommerce store with your ReferralCandy API credentials
3. ReferralCandy tracks WooCommerce orders and attributes purchases to referrers automatically
4. Configure rewards and email timing in the ReferralCandy dashboard (same as Shopify above)

**Referral Hero for WooCommerce:**
1. Install the **Referral Hero** WooCommerce plugin
2. Configure a campaign and set reward type to WooCommerce coupon code
3. Referral Hero issues a unique coupon code to each referee upon signup and notifies the referrer when they convert

**Manual referral program with AutomateWoo:**
- If you prefer full control, use **AutomateWoo** to trigger referral emails and issue discount codes
- AutomateWoo has a built-in Referral workflow template under **AutomateWoo → Workflows → Referrals**

---

#### BigCommerce

**ReferralCandy for BigCommerce:**

1. Go to **Apps → Search "ReferralCandy"** and install
2. Configuration is the same as the Shopify version
3. ReferralCandy tracks BigCommerce orders and issues BigCommerce discount codes as rewards

---

#### Custom / Headless

For headless storefronts, build referral tracking with tiered rewards and fraud detection:

```typescript
// lib/referrals.ts
import { randomBytes } from 'crypto';

// Generate a unique, human-friendly referral code per customer
export async function getOrCreateReferralCode(customerId: string): Promise<string> {
  const existing = await db.referralCodes.findFirst({ where: { customerId } });
  if (existing) return existing.code;

  const customer = await db.customers.findUnique({ where: { id: customerId } });
  const prefix = (customer!.firstName ?? 'USER').slice(0, 4).toUpperCase();
  const suffix = randomBytes(3).toString('hex').toUpperCase();
  const code = `${prefix}${suffix}`; // e.g., JANE3A9F

  await db.referralCodes.create({ data: { customerId, code } });
  return code;
}

// Middleware: capture referral code from ?ref= URL param into a 30-day cookie
export function referralTrackingMiddleware(req: Request, res: Response, next: NextFunction) {
  const code = req.query.ref as string;
  if (code && !req.cookies.ref_code) {
    res.cookie('ref_code', code, { maxAge: 30 * 86400000, httpOnly: true, secure: true, sameSite: 'lax' });
  }
  next();
}

// Tiered rewards: reward amount increases as referrer accumulates successful referrals
const REFERRAL_TIERS = [
  { minReferrals: 0,  referrerRewardCents: 1000, refereeRewardCents: 1000 }, // $10/$10
  { minReferrals: 5,  referrerRewardCents: 1500, refereeRewardCents: 1000 }, // $15/$10 after 5
  { minReferrals: 10, referrerRewardCents: 2500, refereeRewardCents: 1500 }, // $25/$15 after 10
];

function getReferralReward(successfulReferrals: number) {
  return [...REFERRAL_TIERS].reverse().find(t => successfulReferrals >= t.minReferrals)!;
}

// On new account creation: attribute referral, run fraud checks
export async function onCustomerCreated(customerId: string, refCode: string | undefined) {
  if (!refCode) return;

  const referralCode = await db.referralCodes.findFirst({ where: { code: refCode } });
  if (!referralCode || referralCode.customerId === customerId) return; // block self-referral

  // Fraud check: same shipping address as referrer
  const [referee, referrer] = await Promise.all([
    db.customers.findUnique({ where: { id: customerId }, include: { addresses: true } }),
    db.customers.findUnique({ where: { id: referralCode.customerId }, include: { addresses: true } }),
  ]);

  const refereeAddr = referee?.addresses[0]?.addressHash;
  const referrerAddr = referrer?.addresses[0]?.addressHash;
  if (refereeAddr && refereeAddr === referrerAddr) return; // same address = block

  await db.referrals.create({ data: { referrerId: referralCode.customerId, refereeId: customerId, code: refCode, status: 'pending' } });
}

// On referee's first purchase: issue rewards to both parties
export async function onRefereeFirstPurchase(refereeId: string, orderId: string) {