Feature: Add referral program — share SYNCRO and earn perks

[Calebux]

Description

Word-of-mouth is the most effective growth channel for tools like SYNCRO. A referral program lets existing users invite friends and earn rewards (extended free tier, premium features, credits), while giving referred users an incentive to join.

Feature Scope

Referral System

Each user gets a unique referral link

https://syncro.app/ref/abc123

Referral Tracking

CREATE TABLE referrals (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  referrer_user_id UUID REFERENCES profiles(id),
  referred_user_id UUID REFERENCES profiles(id),
  referral_code TEXT NOT NULL,
  status TEXT DEFAULT 'pending', -- pending, signed_up, converted
  signed_up_at TIMESTAMPTZ,
  converted_at TIMESTAMPTZ,
  reward_granted BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

ALTER TABLE profiles ADD COLUMN referral_code TEXT UNIQUE;
ALTER TABLE profiles ADD COLUMN referred_by UUID REFERENCES profiles(id);

Referral Flow

1. User A shares their referral link
2. User B opens the link → referral code saved in cookie/localStorage
3. User B signs up → referred_by set to User A's ID
4. When User B adds their first subscription ("converted") → trigger reward

Rewards (configurable)

• Referrer: 1 month free premium per successful referral
• Referred: 14-day free trial extended to 30 days

UI Components

Share Panel (in settings or dashboard)

Invite friends to SYNCRO
━━━━━━━━━━━━━━━━━━━━━━━
Your referral link:
https://syncro.app/ref/abc123   [Copy]

[Share on Twitter]  [Share on WhatsApp]  [Copy Link]

You've referred: 3 friends
Rewards earned: 2 months free premium

Backend Endpoints

GET  /api/referrals/stats     — referral count, conversions, rewards
POST /api/referrals/validate  — validate referral code at signup
GET  /api/referrals/code      — get user's referral code (generate if missing)

Acceptance Criteria

• Unique referral code generated per user
• Referral tracked from signup through first conversion
• Rewards automatically granted on conversion
• Share panel in dashboard settings
• Social share buttons with pre-filled message
• Referral stats page showing earnings

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 150 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[devAgatha]

@devAgatha has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

Hi maintainer. I can work on this issue, please assign.

Thank you!

ℹ️ Repo Maintainers: To accept this application, review their application or assign @devAgatha to this issue.