ATLAS
Affiliate & Referral Program

Dual-role referral engine powering contractor commission tiers and poster friend referrals with Stripe Connect payouts.

1 Referral Hub
2 Tier & Earnings
3 Tracking
4 Expand
1 Referral Hub & Tiers
2 Tracking & Earnings
1 Referral Dashboard
Section 1 — Referral Hub
1 / Contractor Dashboard
9:41
Affiliate Dashboard
$2,450
Total Earned
$375
Pending
28
Total Referrals
$680
This Month
Your Referral Code
MIKE-3BIDS
https://3bids.io/ref/MIKE-3BIDS
Referral Stats Silver Tier
Converted 19
Conversion Rate 67.8%
Silver Gold 19 / 30 referrals
11 more referrals to unlock Gold tier

AffiliateDashboard — contractor earnings overview with tier progress

useQuery(api.features.affiliates.getDashboard)

2 / QR Code & Share
9:41
QR Code Generator
Home Improvement Platform
Scan to get started!
Code: MIKE-3BIDS
Your Referral Link
https://3bids.io/ref/MIKE-3BIDS
Share Via
How It Works
1
Share your QR code Print on business cards or display at job sites
2
They sign up New user scans and creates their account
3
You earn commission Earn on every job they complete for 2 full years
View Terms & Conditions

AffiliateQRCode — QR code generator with customization & sharing

useQuery(api.features.affiliates.getReferralLink)

3 / Poster Referral Hub
9:41
Refer & Earn
Share & Earn 2 years of referral bonuses
https://3bids.io/ref/SARAH-HOME
$185
Total Earned
7
Referrals
Invited Friends View All
JD
Jennifer Davis Signed up Dec 14
Reward Earned
MR
Mark Rodriguez Signed up Jan 8
First Job Posted
AL
Amy Lin Signed up Feb 2
Signed Up

PosterAffiliateDashboard — poster referral hub with friend tracking

useQuery(api.features.affiliates.getDashboard)

Section 2 — Tier & Earnings
4 / Tier Upgrade
9:41
Tier Upgrade
Current Tier
Silver
Bronze
Completed
$25 per converted referral
2% commission for 12 months
Silver
Current
$50 per converted referral
3% commission for 18 months
Priority support access
19 / 30 referrals to Gold 63%
Gold
Next Tier
$75 per converted referral
4% commission for 24 months
Dedicated account manager
Early access to new features
Requires: 30 referrals + $5,000 revenue
Platinum
Locked
$100 per converted referral
5% commission unlimited
Custom referral materials
Requires: 75 referrals + $15,000 revenue

TierUpgradeScreen — tier progression with benefits & milestones

useQuery(api.features.affiliates.getTierStatus)

5 / Earnings Calculator
9:41
Income Calculator
Projected 2-Year Earnings
$14,400
Based on your current inputs
$600
Monthly Avg
480
Total Referrals
1,440
Total Jobs
Inputs Reset
Referring
Homeowners
Contractors
Referrals per Month 20
−
+
Average Job Size $5,000
−
+
Commission Tier
2% Standard
3% Super
4% Agency
Quarterly Breakdown
Q1 (Mo 1–6)
$1,800
120 referrals
Q2 (Mo 7–12)
$3,000
120 referrals
Q3 (Mo 13–18)
$4,200
120 referrals
Q4 (Mo 19–24)
$5,400
120 referrals

IncomeCalculator — interactive 2-year projection with slider inputs

Local state: initialReferrals, growthRate, avgJobSize, commissionTier

6 / Stripe Connect Setup
9:41
Stripe Connect
Stripe Connect
Not Connected
Connect your Stripe account
Set up Stripe Connect to receive your affiliate commission payments directly to your bank.
How Stripe Connect Works
1
Create your Stripe Express account Enter your business and banking details securely
2
Verify your identity Stripe may require identity verification for security
3
Start receiving payouts Commission payments deposited directly to your bank
Benefits of Stripe Connect
Bank-level security for your payments
Fast payouts to your bank account
Track earnings in real-time
Works with banks worldwide
Connected State Preview
Account Verified
Payouts Enabled
Chase Bank ****4829
Powered by Stripe

StripeConnectSetup — bank connection with status states (not_connected, pending, active)

useQuery(api.features.affiliates.getStripeAccountStatus), useMutation(api.features.affiliates.createStripeAccountLink)

Section 3 — Tracking
7 / Referral History
9:41
Referral History
All (28)
Converted
Pending
Expired
JH
James Henderson
Referred Jan 15, 2026
Converted — 3 jobs completed
+$150 Earned
SK
Sarah Kim
Referred Feb 3, 2026
Signed up — pending first job
$0 Pending
TB
Tyler Brooks
Referred Dec 28, 2025
Converted — 7 jobs completed
+$350 Earned
AP
Anna Petrovich
Referred Oct 5, 2025
Expired — no activity in 90 days
$0 Expired
DW
Derek Washington
Referred Feb 18, 2026
Just signed up today
$0 Pending

ReferralHistory — filterable referral list with conversion timelines

useQuery(api.features.affiliates.getReferrals, { status?, limit: 20 })

8 / Payout History
9:41
Payout History
Lifetime Payouts
$2,075
Monthly Earnings Last 6 months
Sep
Oct
Nov
Dec
Jan
Feb
Transactions
Export
February Payout Feb 15, 2026 · Bank Transfer
$680.00 Completed
January Bonus Jan 31, 2026 · Bank Transfer
$125.00 Processing
January Payout Jan 15, 2026 · Bank Transfer
$520.00 Completed
December Payout Dec 15, 2025 · Bank Transfer
$375.00 Completed
November Payout Nov 15, 2025 · Bank Transfer
$375.00 Completed
Running Total $2,075.00
5 payouts via Chase Bank ****4829

PayoutHistory — earnings chart with payout list & export

useQuery(api.features.affiliates.getPayouts, { limit: 20 })

Section 4 — Expand
9 / Contractor Affiliate Dashboard
9:41
Affiliate Dashboard
$4,280
Total Earned
$625
Pending
$1,150
This Month
42
Total Referrals
Gold Tier
Gold
Gold Platinum 42 / 60 referrals
18 more referrals to unlock Platinum tier
10% Commission
$100 Per Referral
2 yr Duration
Recent Referrals View All
DM
David Martinez Referred Mar 22 · Poster
+$100 Converted
KL
Karen Lewis Referred Mar 18 · Contractor
$0 Pending
RJ
Robert Johnson Referred Mar 10 · Poster
+$100 Converted
TP
Tina Patel Referred Mar 5 · Poster
+$75 First Job
Pro Tip: Share your referral link at every job site. Homeowners who see your work firsthand convert 3x faster.

AffiliateDashboard (Expanded) — full earnings stats, tier progress, recent referrals

useQuery(api.features.affiliates.getDashboard)

10 / QR Save to Gallery
9:41
Save QR Code
Your Personalized QR Code
Mike’s Plumbing & HVAC
Code: MIKE-3BIDS
Share Link
https://3bids.io/ref/MIKE-3BIDS
How to Use Your QR Code
1
Save to your phone’s gallery for quick access
2
Print on business cards, truck wraps, or flyers
3
Display at job sites — customers scan to sign up
4
Earn commission on every job they complete for 2 years
Pro Tip: Add the QR code to your email signature. Every email becomes a referral opportunity.

AffiliateQRCode (Save) — large QR display with save-to-gallery & sharing options

useQuery(api.features.affiliates.getReferralLink) • MediaLibrary.saveToLibraryAsync()

11 / Refer Restructure
9:41
Referral Links
New /refer/ URL Structure
3bids.io/refer/MIKE-3BIDS
Replaces /ref/ with cleaner /refer/ path
Deep Link Preview
3Bids — Home Services 3bids.io
Mike from Mike’s Plumbing invited you to 3Bids. Get 3 bids on your next home project.
Verified referral · Tracked automatically
Referral Tracking
Live
Link Views
847
Sign-ups
42
Conversions
31
Conversion Rate
73.8%
Your Links
PRIMARY 3bids.io/refer/MIKE-3BIDS
QR LINK 3bids.io/refer/MIKE-3BIDS?src=qr
SMS 3bids.io/refer/MIKE-3BIDS?src=sms
Pro Tip: Use source-tagged links (QR, SMS, Email) to see which channel drives the most conversions.

ReferRestructure — new /refer/ URL structure with deep link preview & tracking

useQuery(api.features.affiliates.getReferralLink) • trackReferral()

Data Architecture
Schema Tables
affiliates — per-user affiliate config
Affiliate code, tier (standard/bronze/silver/gold/platinum), linked agency, Stripe Connect account ID, total earnings, commission rate

affiliateReferrals — individual referrals
Referrer ID, referred user ID, status (pending/active/converted/expired), reward amount, conversion date

affiliatePayouts — payout records
Affiliate ID, amount, method (bank_transfer), Stripe transfer ID, status (processing/completed/failed), period
Hooks & Queries
useAffiliate — dashboard data, stats, tier status

useReferrals — referral list, filtered by status

features.affiliates.getDashboard
features.affiliates.getReferralLink
features.affiliates.getTierStatus
features.affiliates.getStripeAccountStatus

generateReferralCode — mutation
trackReferral — mutation
requestPayout — mutation

Integration: Stripe Connect (Express accounts, transfers, payouts)
Referral Hub & Tiers
Referral Hub & Tiers
9:41
Referral Hub & Tiers
Top Referrers
156
Referrals
$12.4K
Earned
34%
Conversion
Gold
Your Tier
Top Referrers
Jake Morrison
Gold Tier — 24 referrals
$2,400
Amy Torres
Silver Tier — 12 referrals
$960
Dan Kowalski
Bronze Tier — 6 referrals
$360
Tracking & Earnings
Tracking & Earnings
9:41
Tracking & Earnings
Details
Title
Spring Roof Referral Campaign
Description
$50 bonus per qualified referral that books a job.
Configuration
Auto-Approve Referrals
Email Notifications
Preview
Referral Link Preview
Shareable landing page with your branding, service areas, and referral tracking.
Performance
68%
Conversion
+23%
MoM
$2.4K
Earned
Referral Dashboard
Referral Dashboard
https://app.3bids.io/contractor/referrals
3Bids
Main
Dashboard ⌘1
Links ⌘2
Tiers ⌘3
Network ⌘4
Payouts ⌘5
MK
Mike Kowalski
Contractor
Settings ⌘,

Referral Dashboard

1,847
Total Referrals
$42.8K
Total Payouts
38%
Conversion Rate
247
Active Affiliates
Recent Activity
Jake Morrison
Gold Tier — 24 referrals
Amy Torres
Silver Tier — 12 referrals
Dan Kowalski
Bronze Tier — 6 referrals
Performance

Status Flow

pending → active → completed

Key Design Decisions

Design Pattern
TODO: Add design decision