Affiliate System Configuration

The affiliate system lets users invite new users through referral links and earn cash commissions from each successful payment made by referred users. It also supports two-way signup rewards, so both the referrer and referred user can receive credits.

Related Pages

System Overview

Quick Enable

The affiliate system is disabled by default. After configuring payment, risk control, withdrawal, and support workflows, set AFFILIATE_ENABLED=true to enable it.

After enabling it, the user dashboard automatically shows Affiliate and Withdrawal tabs, and the admin sidebar shows Commissions and Withdrawals navigation items.

Minimal Configuration

You must explicitly enable the feature; all other values can use their defaults:

# Required: disabled by default
AFFILIATE_ENABLED=true
# Optional: all other values have reasonable defaults
# AFFILIATE_COMMISSION_RATE=0.20
# AFFILIATE_REFERRER_SIGNUP_BONUS=10
# AFFILIATE_REFEREE_SIGNUP_BONUS=10
# AFFILIATE_MIN_WITHDRAWAL=100
# AFFILIATE_COOKIE_EXPIRY_DAYS=30

Disable the Affiliate System

AFFILIATE_ENABLED=false

After disabling:

• The user dashboard hides Affiliate / Withdrawal tabs
• The admin dashboard hides commission / withdrawal navigation
• APIs return enabled: false
• Payment Webhooks skip commission processing

Environment Variables

Currency Limitation

The current affiliate system supports only one currency. The commission balance field, commissionBalance, is a simple accumulated number and does not separate balances by currency.

If your config/payment.ts includes plans in multiple currencies, such as USD and CNY, make sure all plans participating in affiliate commissions use the same currency. Mixing currencies makes the balance number meaningless.

Recommended setup:

1. Set AFFILIATE_CURRENCY to your main billing currency (default USD)
2. Ensure all commission-enabled plans in config/payment.ts use the same currency as AFFILIATE_CURRENCY
3. If you have both CNY and USD plans, consider enabling commissions for only one currency by adding filtering logic in your Webhook handler

Configuration Examples

# High-commission mode for high-ticket products
AFFILIATE_COMMISSION_RATE=0.30
AFFILIATE_MIN_WITHDRAWAL=50

# Fixed commission mode: 5 per order
AFFILIATE_FIXED_COMMISSION_AMOUNT=5

# Larger signup rewards to encourage referrals
AFFILIATE_REFERRER_SIGNUP_BONUS=50
AFFILIATE_REFEREE_SIGNUP_BONUS=20

Workflows

Referral Signup Flow

1. User A gets a referral link from the dashboard: https://yourapp.com?ref=NjMDryrv
2. User B opens the link
3. Middleware stores the ref parameter in a cookie (valid for 30 days)
4. User B signs up and logs in
5. The first dashboard visit triggers claim automatically
6. The system records the referral relationship in the database
7. Both users receive credit rewards if the configured reward amounts are > 0

Commission Flow

1. User B, the referred user, purchases any paid plan or credits package
2. Payment succeeds → payment Webhook is triggered
3. After order processing, the Webhook calls processReferralCommission(orderId)
4. The system checks referral information in the order metadata
5. The commission amount is calculated from the configured rate
6. A commission record is created and added to the referrer's commissionBalance

Withdrawal Flow

1. User A requests a withdrawal from the dashboard Withdrawal tab
2. User enters amount, payment method, and receiving account
3. The system validates balance ≥ withdrawal amount ≥ minimum withdrawal amount
4. Balance is deducted immediately to prevent duplicate withdrawals
5. Admin reviews the request:
   - Approve (completed): admin transfers funds manually
   - Reject (rejected): balance is returned automatically

Admin Operations

View Commission Records

Open /admin/commissions to:

• View commission records for all users
• Search by email
• View commission amount, order amount, commission rate, and status

Approve Withdrawals

Open /admin/withdrawals to:

• View all withdrawal requests
• Search by email
• Click Approve to approve a withdrawal (manual transfer required)
• Click Reject to reject a withdrawal (balance is returned automatically)

FAQ

User Cannot See the Affiliate Tab?

Check that AFFILIATE_ENABLED=true is configured. Restart the development server for the configuration to take effect.

Commission Was Not Generated?

1. Confirm the referred user's order metadata includes referralCode and referrerId
2. Check payment Webhook logs for [Affiliate][Commission]
3. Confirm processReferralCommission(orderId) is called in the relevant payment Webhook handler

Referral Link Does Not Work?

1. Confirm the link includes the ?ref=CODE parameter
2. Check whether the browser has a referral_code cookie
3. The user must sign up and log in before claiming
4. Each user can only be referred once

SQLite Database Compatibility?

The system supports both PostgreSQL and SQLite. SQL uses standard CAST() syntax and has passed full E2E tests on both databases.

Related Docs

• Credits System Configuration - Signup rewards are issued through the credits system
• Payment Testing Guide - Test payment Webhooks that trigger commissions
• Database Configuration - PostgreSQL / SQLite switching