Referral System Design
A three-tier affiliate engine built on unique invite codes, HMAC-signed attribution cookies, and Upstash KV for real-time credit tracking.
Invite Code Generation
Each user receives a deterministic 8-character alphanumeric code derived from their account UUID via HMAC-SHA256 truncated to 48 bits. Codes are stored in Upstash KV with a TTL matching the user's subscription tier. Collision probability is below 2-40 for up to 10 million users.
Attribution Flow
- Visitor lands on
/r/<code> - Edge middleware validates code against KV, sets a signed attribution cookie (HttpOnly, SameSite=Lax, 30-day expiry)
- Cookie persists across sessions; last-click attribution wins with a 7-day cooldown to prevent self-referral cycling
- On successful purchase, SellAuth webhook fires; Meridian backend resolves the cookie, credits the referrer in KV
Tier Structure
Payout & Anti-Abuse
Payouts are batched weekly via SellAuth balance transfers with a $25 minimum threshold. Each referral is validated against IP diversity, browser fingerprint entropy, and purchase velocity. Fraudulent clusters trigger automatic code revocation and clawback of credited commissions. The circuit breaker disables a code after 3 chargebacks within a rolling 30-day window.
Dashboard Integration
Referrers see real-time stats via the dashboard: total clicks, conversions, pending payouts, and tier breakdown. Data is served from Upstash KV sorted sets with 60-second cache invalidation. The shareable link widget copies the full referral URL with a single click and includes a pre-rendered OG image for social previews.