Help & Documentation

Complete guide to using the Echo Referral System admin panel.

Quick Start Guide

1. Start the Development Server

cd /Users/jill/Documents/Echo
npm run dev

The server will start at http://localhost:3000 (or next available port).

2. Set Up Your First Tenant

Go to Tenants → Add Tenant to create your first brand/organization.

3. Create a Campaign

Go to Campaigns → Add Campaign to set up commission rules.

4. Add Affiliates

Go to Affiliates → Add Affiliate to register partners. A unique referral code is auto-generated.

5. Share Referral Links

Give affiliates their referral URL: yoursite.com/?ref=CODE

Test Links & URLs

Interactive Test Page

Use the built-in test page to simulate the complete referral flow:

Open Test Page →

Referral Link Format

Append ?ref=CODE to any page on your site:

http://localhost:3000/?ref=AFFILIATE_CODEHomepage
http://localhost:3000/pricing?ref=AFFILIATE_CODEPricing page
http://localhost:3000/signup?ref=AFFILIATE_CODESignup page

API Endpoints for Testing

Endpoint	Method	Purpose
/api/referrals/track	GET	Record a visit with referral code
/api/referrals/attribute	POST	Link user signup to affiliate
/api/webhooks/stripe	POST	Handle Stripe payment events
/api/test/referral-status	GET	Check current referral cookie
/api/test/simulate-signup	POST	Simulate user signup with attribution

Creating Referral Codes

Automatic Code Generation

When you create a new affiliate, a unique 8-character referral code is automatically generated. This code is globally unique across all tenants.

Steps to Create a New Code

Go to Affiliates in the left navigation
Click Add Affiliate button
Select a Tenant (organization/brand)
Select a Campaign (commission structure)
Enter the affiliate's name and email
Click Add Affiliate
The referral code appears automatically in the affiliates list

Code Format

Codes are 8 characters, alphanumeric, uppercase. Example:

IU586ASS

Navigation Guide

📊

Dashboard

The main overview page showing key metrics at a glance.

Total Tenants - Number of organizations using the platform
Active Campaigns - Currently running referral programs
Total Affiliates - All registered affiliate partners
Total Commissions - Sum of all earned commissions
Pending Payouts - Commissions awaiting the lock period to end
Paid Out - Total amount already paid to affiliates

🏢

Tenants

Manage organizations or brands. Each tenant is an isolated entity with its own campaigns and affiliates.

Use Cases:

White-label the referral system for different clients
Separate departments or product lines within one company
Agency managing multiple brands

Fields:

Name - Display name (e.g., "Acme Corp")
Slug - URL-safe identifier (e.g., "acme")
Settings - JSON for branding (logo, colors, domain)

🎯

Campaigns

Define commission structures and rules. Each campaign belongs to a tenant and has specific payout terms.

Fields:

Name - Campaign identifier (e.g., "Partner Program")
Tenant - Which organization owns this campaign
Commission Type - PERCENTAGE or FIXED amount
Commission Value - Percentage (e.g., 20%) or fixed cents (e.g., $50)
Cookie Duration - How long the referral cookie lasts (days)
Recurring Model:
- First Payment - Commission on first payment only
- First Year - Commission on all payments for 12 months
- Lifetime - Commission on every payment forever

👥

Affiliates

Manage your affiliate partners. Each affiliate gets a unique referral code and belongs to one campaign.

Fields:

Name - Affiliate's full name
Email - Contact email (must be unique per tenant)
Campaign - Which commission structure applies
Status:
- Pending - Awaiting approval
- Active - Can earn commissions
- Suspended - Temporarily disabled
- Terminated - Permanently removed
Stripe Connect - Connected Stripe account for payouts

Affiliate Actions:

Manage - Edit details, change status, view referral codes
View Referrals - See users they've referred
View Commissions - See their earnings history

💰

Commissions

Track all commission records. Commissions are created automatically when referred users make payments.

Commission Statuses:

Pending - Created, waiting for 30-day lock period
Due - Lock period passed, ready for payout
Paid - Successfully paid to affiliate
Void - Cancelled (e.g., customer refunded)
Clawback - Recovering a previously paid commission

Displayed Information:

Date - When the commission was created
Affiliate - Who earned it
Transaction - Stripe Invoice/Event ID
Amount - Original transaction value
Commission - Amount earned by affiliate
Lock Date - When it becomes payable

📄

Statements

Generate payout statements and process affiliate payments via Stripe Connect.

How It Works:

Click Generate Statements to see all due commissions
Review statements grouped by affiliate
Click Process Payouts to transfer funds
Funds are sent via Stripe Connect to affiliate accounts

⚠️ Important:

Affiliates must connect their Stripe account to receive payouts
Only commissions with status "DUE" are included
Processing payouts is irreversible

Complete Referral Flow

User Clicks Referral Link

yoursite.com/?ref=CODE → Cookie set for 30 days

User Signs Up

Attribution API links user to affiliate permanently

User Makes Payment

Stripe webhook creates commission (PENDING status)

30-Day Lock Period

Protects against refunds and chargebacks

Commission Becomes DUE

Ready for payout in Statements page

Process Payout

Stripe Connect transfer to affiliate account

Environment Configuration

Required environment variables in .env or .env.local:

# Database
DATABASE_URL="file:./dev.db"

# Stripe (required for payments)
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

# Referral Settings
REFERRAL_COOKIE_NAME="echo_ref"
COMMISSION_LOCK_DAYS="30"

Troubleshooting

Referral cookie not being set?

Make sure the URL includes ?ref=CODE and the code exists in the database. Check browser dev tools → Application → Cookies.

Commissions not appearing?

Commissions are created by Stripe webhooks. Ensure your webhook endpoint is configured in Stripe Dashboard and STRIPE_WEBHOOK_SECRET is set correctly.

Payouts failing?

Affiliates must have a connected Stripe account. Check the affiliate's Stripe Connect status in the Affiliates → Manage page.

Database errors?

Run npx prisma migrate dev to ensure schema is up to date, then npx prisma generate to regenerate the client.