Refer & Earn

Overview

The refer-and-earn module provides a referral program where users generate unique codes to invite others. Both referrer and referee earn rewards, with payouts via Stripe Connect.

Module path: src/lib/modules/refer-and-earn/ Route: /refer-and-earn

Referral Code System

interface ReferralCode {
  code: string;              // e.g., "JOHN123"
  userId: string;            // Code owner
  isActive: boolean;
  usageCount: number;
  maxUsage: number | null;   // null = unlimited
  expiresAt?: Timestamp;
  customUrl?: string;        // Vanity URL
}

Code Generation Strategies

• generateReferralCodeFromName(name) - Name-based code
• generateReferralCodeFromEmail(email) - Email-based code
• generateUniqueReferralCode() - Random unique code

Referral Tracking

interface Referral {
  referrerId: string;
  refereeId: string;
  status: 'pending' | 'completed' | 'expired' | 'cancelled';
  source: ReferralSource;
  conversionEvent: ConversionEvent;
  rewards: { referrer: Reward; referee: Reward };
  metadata: { utmParams; ipAddress; userAgent };
}

type ReferralSource = 'email' | 'social' | 'direct' | 'sms' | 'affiliate' | 'qr_code';
type ConversionEvent = 'signup' | 'email_verification' | 'first_purchase' | 'subscription' | 'minimum_spend' | 'custom';

Reward System

interface Reward {
  type: 'credit' | 'discount' | 'points' | 'product' | 'subscription';
  status: 'pending' | 'issued' | 'redeemed' | 'expired' | 'cancelled';
  amount: number;
  discountCode?: string;
  minimumSpend?: number;
  isPercentage?: boolean;
  expiresAt?: Timestamp;
}

User Tiers: Bronze, Silver, Gold, Platinum

Stripe Connect Integration

interface ReferralConnectAccount {
  userId: string;
  stripeAccountId: string;
  accountStatus: 'pending' | 'verified' | 'restricted';
  chargesEnabled: boolean;
  payoutsEnabled: boolean;
  requirements: {
    currentlyDue: string[];
    eventuallyDue: string[];
    pastDue: string[];
  };
}

State Management

referralStore

referralStore.referrals;         // All user's referrals
referralStore.referralCodes;     // All codes owned by user
referralStore.totalReferrals;
referralStore.totalReferralCodes;

referralConnectManager

referralConnectManager.connectAccount;   // Stripe Connect details
referralConnectManager.accountStatus;    // Status flags

Services

ReferralService

referralService.createReferralCodeForUser();
referralService.createAdditionalReferralCodeForUser();
referralService.checkReferralCodeExists(code);
referralService.deactivateReferralCode(code);
referralService.reactivateReferralCode(code);
referralService.trackReferralSignup(code, userId);

CookieManager

Persists referral code in cookies across sessions:

• Save/retrieve referral code
• Manage UTM parameters
• Track referral data

Components

Component	Purpose
refer-header.svelte	Page header with generate code CTA
general-stats.svelte	Referral performance stats
stats-card.svelte	Individual stat display
referral-codes.svelte	All codes with usage data
referrals-table.svelte	Referral list
recent-activity.svelte	Recent referral activity
generate-referral-code-dialog.svelte	Initial code creation
generate-additional-code-dialog.svelte	Additional codes
invite-friend-button.svelte	Share referral link
payout-dialog.svelte	Stripe Connect payout

Waiting for Approval Gate

The /waiting-for-approve page integrates with referrals:

• Users can enter a referral code to get approved during private beta
• Valid referral code + available registry slots = automatic approval
• Updates user document with referral relationship