The referral module gives each user a referral code and tracks referred signups through conversion and reward states.
Lifecycle
| Status | Meaning |
|---|---|
pending | Referral code exists, no signup yet |
signed_up | A referred user created an account |
converted | The referred user became a paying customer |
rewarded | The reward was issued |
Key files
| File | Purpose |
|---|---|
src/lib/referrals/index.ts | Referral code, signup, conversion, reward, stats helpers |
src/app/api/referrals/route.ts | Referral stats and leaderboard API |
referral table | Stores referral code and lifecycle state |
Configuration
REFERRAL_REWARD_AMOUNT="10"
REFERRAL_REWARD_TYPE="credit"
REFERRAL_REWARD_TYPE supports credit, discount, or cash. Adapt the reward issuance step to match your billing provider and business model.
Typical integration points
- Call
getOrCreateReferralCode(userId)when showing a referral dashboard. - Capture the code from signup links.
- Call
recordSignup(code, referredUserId)after account creation. - Call
markConverted(referredUserId)after the first paid purchase. - Call
markRewarded(referralId)after issuing the reward.
Feature flag
ENABLE_REFERRALS="false"
When disabled, referral dashboard and API surfaces return 404.