Referrals

Referral System

Account-centric referral program: each account owns one active short code, and both sides earn credits when the configured trigger fires. Paid rewards are bound to the exact positive local payment that qualified them, so an unrelated refund or dispute cannot claw them back. The system is feature-gated via the REFERRAL_ENABLED environment variable (server-only, no NEXT_PUBLIC_ prefix) and surfaces as 404 when disabled — invisible until you turn it on.

Feature Gate

Set REFERRAL_ENABLED=true in your environment to enable the full user dashboard, signup banner, tracking redirect, and admin console. The flag is read once inside config/referral.ts and exposed as referralConfig.enabled / isReferralEnabled(). Components and routes must import the helper — never read process.env directly.

Configuration (config/referral.ts)

Trigger Semantics

Attribution Flow

1. Visitor hits /?ref=ABCD1234  or  /[locale]/refer/ABCD1234
            │
            ▼
2. Middleware / route — validates regex, sets httpOnly bsk_ref cookie
   (Secure, SameSite=Lax, 30-day window) — no DB call in hot path
            │
            ▼
3. Paid checkout authorizes the requested billing Account, then applies
   the referral cookie before returning the Stripe URL. B2B targets the
   verified workspace; B2C targets the verified personal Account.
            │
            ▼
4. Onboarding awaits POST /api/referral/attribute as a non-blocking fallback.
   It resolves an owned workspace in B2B or personal Account in B2C. The
   trusted cookie flow may reconcile a payment that committed first; manual
   code application cannot reuse a historical payment.
            │
            ▼
5. referrals row inserted (status='pending' for paid triggers or 'rewarded'
   immediately when trigger = on_signup).
            │
            ▼
6. A paid webhook passes the exact finalized payments.id to the qualification
   RPC. Zero, fully refunded, missing, or foreign-Account payments are rejected.
   Full refunds / lost disputes reverse only the referral linked to that
   payment via qualifying_payment_id.

Database Schema

Two tables, both row-level-security protected with SELECT scoped by membership on the referrer account. Writes go exclusively through SECURITY DEFINER RPCs (no INSERT/UPDATE/DELETE policies exposed to clients).

SECURITY DEFINER RPCs

Every RPC runs REVOKE EXECUTE FROM authenticated, anon; GRANT TO service_role; with an auth.role() defense-in-depth check inside the body. Credit movements go through add_credits / decrement_credits only — the referral RPCs never touch credits_balance directly.

Stripe Webhook Integration

Billing hooks call maybeQualifyOnPurchase(accountId, eventType, qualifyingPaymentId) from core/billing/mutations.ts only after a positive local payment row is finalized. Refund and lost-dispute handling call reverseReferralForPayment(paymentId, reason), so the clawback is tied to the payment that originally qualified the referral. All referral hooks are try/catch-wrapped so transient referral failures never break billing.

User Dashboard

The user dashboard at /private-dashboard/referrals is a Server Component that fetches the code, stats, and referrals list in parallel via Promise.all. Only the share card is 'use client' (clipboard + Web Share API). A signup banner reads the bsk_ref cookie server-side and tells the invitee how many credits they'll receive.

Admin Console

The admin panel lives under /admin-dashboard/referrals with four pages: overview (KPI grid + top-10 referrers from the aggregate RPC, cached 60s), filterable list with cursor pagination, detail page with the full timeline plus linked credit_transactions and admin_logs audit trail, and a codes management table with a deactivate action. Every admin mutation (reverse / reject / deactivate) writes an admin_logs row with { actor_user_id, action, target_id, details: { reason, before } }.

API Endpoints

Environment Variables

Security Invariants

• Self-referral blocked at the DB level (CHECK constraint) and at the RPC level (same-owner check on accounts.owner_user_id)
• One referral per account for life (UNIQUE(referred_account_id))
• Paid rewards require a positive persisted payment belonging to the referred Account; zero/free, missing, foreign-Account, and fully refunded payments are rejected
• Attribution and webhook qualification serialize on the referred Account, closing the payment-before-attribution race
• Each paid reward stores qualifying_payment_id; refund and dispute clawbacks use that exact payment
• Historical-payment reconciliation is available only to trusted cookie attribution, never manual code application
• One active code per account (partial unique index on account_id WHERE active)
• IP + User-Agent stored as SHA-256 hashes salted with REFERRAL_SALT — never raw PII
• Credits move only through add_credits / decrement_credits RPCs; every mutation lands a credit_transactions row with referral, role, trigger, and qualifying-payment metadata for audit
• Refunds and lost disputes automatically claw back granted credits
• Every admin mutation writes an admin_logs entry
• Feature gate returns 404 (not 403) so the surface is invisible when disabled
• CSRF enforced on every state-changing endpoint via apiSecurity.* (Double Submit Cookie)