Refer & Earn

Route

Route	Purpose
/refer-and-earn	Referral dashboard with stats, codes, and activity

---

Referral Code Generation

Auto-Generated Codes

• Based on user’s displayName or email
• Format: REF + random 6 characters
• Can regenerate for different options

Custom Codes

Constraint	Rule
Length	3-20 characters
Characters	Uppercase letters and numbers only
Uniqueness	Checked against Firestore with 500ms debounce

Code Document

Path: referralCodes/{code}

{
  code, userId, isActive: true,
  usageCount: 0, maxUsage: null,
  createdAt, updatedAt
}

Users can create multiple codes for different campaigns.

---

Sharing

Methods Available

Native Share, Email (mailto), WhatsApp, X/Twitter, LinkedIn, Facebook, Copy Link

Referral URL Format

https://mindhyv.com/?referralCode={code}

Share Message Template

🚀 Join me on MindHyv!
The ultimate platform for creative freelancers.
Start your freelance journey: {referralUrl}
#freelance #creatives #mindhyv

Share Tracking Data

Data Point	Description
Share type	COPY_LINK, NATIVE_SHARE, EMAIL, WHATSAPP, TWITTER, LINKEDIN, FACEBOOK
Timestamps	firstSharedAt, lastSharedAt
Count per method	Incremented per share
totalShares	Aggregate

Stored in user document under referralShareStats.

---

Cookie Tracking

Cookies Set on Referral Visit

Cookie	Content	Expiration	Options
referralCode	Code string	90 days	Path /, SameSite Lax
referralData	JSON: {code, timestamp, source, utmParams}	90 days	Path /, SameSite Lax

UTM Parameters Captured

utm_source, utm_medium, utm_campaign, utm_term, utm_content

Initialization

cookieManager.initializeReferralTracking() runs on every page load:

1. Extracts referralCode from URL
2. Extracts UTM params
3. Saves to cookies
4. Cleans tracking params from browser URL

---

Payout System

Minimum Payout

$35 (per completed referral)

Stripe Connect Integration

• Creates Express account via /api/stripe/create-connect-account
• Account states: No Account, Pending (1-2 business days), Verified, Restricted

Payout Eligibility

canPayout = earnings >= 35 && hasConnectAccount

---

Stats Dashboard

Displayed Metrics

Metric	Calculation
Total Referred Users	All referrals count
Total Paying Referrals	Status === COMPLETED count
Total Earnings	Completed referrals x $35
Active Links	Active referral codes count

Referrals Table Columns

Invoice ID, Referral Link, RateStamp (Elite/Pro/Standard/Free), Source, Conversion Event, Conversion Value, Signup Date

Features: Sorting (all columns), filtering (by code, RateStamp, source), column visibility toggle, pagination (10 rows).

---

Referral Conversion Flow

1. Referee visits referral URL
2. Cookie saved (90 days)
3. Referee signs up
4. trackReferralSignupCallable Cloud Function called with:
   • referralCode, userAgent, ipAddress, UTM params, userData
5. Referral document created
6. Code usageCount incremented
7. Referrer earns reward when referee converts

---

Data Collected for Privacy

Data	Purpose	Stored Where
Referral code	Track attribution	Cookie (90 days) + Firestore
UTM parameters	Campaign tracking	Cookie (90 days) + referral doc
User agent	Fraud detection	Referral document
IP address	Fraud detection	Referral document
Share activity	Analytics	User document
Conversion events	Reward calculation	Referral document