Overview
The Affiliate System lets you create a referral program where your users earn commissions by referring new customers. When a referred customer makes a purchase, the referring affiliate earns a percentage of the order value as commission.
• The system supports:
• Tiered commission rates that reward higher-performing affiliates
• Two commission types — Conversion (new customers) and Retention (returning customers)
• Sub-Affiliate (MLM) engine for multi-level referral chains
• Exception user overrides for custom deals with specific affiliates
How Affiliates Earn Commissions
1. An affiliate shares their unique referral link or coupon code with potential customers.
2. A new customer signs up and makes a purchase using the referral link/coupon.
3. The system automatically calculates the commission based on the affiliate’s current tier and the order amount.
4. The commission is credited to the affiliate’s pending balance.
Example: If an affiliate has a 12% conversion rate and a referred customer places a $500 order, the affiliate earns $60 in commission.
Tier Configuration
Tiers define what commission rate an affiliate earns. There are two types of configurations:
1. Tier Levels
Tier Levels are performance-based brackets that automatically assign commission rates to affiliates based on their metrics. As an affiliate’s performance grows, they progress to higher tiers with better rates.
• Tier Name — A label for the tier (e.g., Beginner, Pro, Expert, VIP)
• Tier Type — The metric used to measure performance
• Value Range — The min/max values that define who falls into this tier
• Commission Rates — The conversion and retention percentages
Example tier structure:
Tier | Value Range | Conversion Rate | Retention Rate |
Beginner | 0 - 9 | 12% | 10% |
Pro | 500 - 1,000 | 15% | 15% |
Expert | 1,000 - 2,000 | 20% | 20% |
VIP | 2,000 - 10,000 | 25% | 25% |
2. Exception Users
Exception Users are individual overrides that assign a custom commission rate to a specific affiliate, regardless of their tier level.
• Special partnerships or influencer deals
• Affiliates with negotiated custom rates
• Temporary promotional rates for specific users
Exception users always take priority over tier levels. If a user has an exception configuration, the tier level is ignored.
Tier Types
The Tier Type determines which metric is used to evaluate an affiliate’s performance and assign them to a tier. All tier levels for your platform must use the same tier type — you cannot mix types.
Tier Type | What It Measures | Example |
Referral Count | Number of unique users referred | Affiliate who referred 15 unique users |
Order Value | Total dollar value of orders from referred users | Referrals generated $5,000 in orders |
Order Count | Total number of orders placed by referred users | Referrals placed 25 orders |
Important: Once you create tier levels with a specific tier type, all tiers must use the same type. To switch types, delete all existing tier levels first.
Commission Rate Types
Each tier configuration includes two commission rates:
Conversion Rate
The commission percentage earned when a new customer makes a purchase through the affiliate’s referral.
Retention Rate
The commission percentage earned when a returning customer makes another purchase through the same affiliate.
Example:
Conversion Rate: 15%, Retention Rate: 10%
Customer buys first time → Affiliate earns 15%
Customer buys again → Affiliate earns 10%
Rates are entered as decimals: 0.12 = 12%, 0.15 = 15%, 0.20 = 20%
Sub-Affiliate Engine (Multi-Level Commissions)
The Sub-Affiliate Engine enables multi-level commissions where both the direct referrer and their uplines earn commissions.
How It Works
• Level 1 = Direct referrer (uses standard Conversion/Retention rates)
• Level 2 = First upline (earns separate sub-affiliate rate)
• Level 3 = Second upline (earns separate sub-affiliate rate)
• Up to Level 5
Commission Calculation Example
Level | Affiliate | Calculation | Commission |
Level 1 | Affiliate A | $1,000 x 10% | $100 |
Level 2 | Affiliate B | $1,000 x 5% | $50 |
Level 3 | Affiliate C | $1,000 x 2% | $20 |
Total commissions paid: $170 from a single $1,000 order.
How Tier Assignment Works
• Exception users are checked first.
• Tier level matching based on performance metrics.
• Automatic progression to higher tiers.
• Highest tier fallback if metrics exceed defined ranges.
Summary
Feature | Description |
Tier Levels | Performance-based commission brackets |
Exception Users | Custom rates for specific affiliates |
Tier Types | Referral Count, Order Value, or Order Count |
Conversion Rate | Commission on new customer purchases |
Retention Rate | Commission on returning customer purchases |
Sub-Affiliate Engine | Multi-level commissions up to 5 levels deep |
Automatic Tier Progression | Affiliates move to higher tiers as they perform |
If you have questions about configuring your affiliate tiers or need help setting up your referral program, reach out to our support team.
Affiliate Models
The system supports three distinct affiliate models, configured per client:
1. Lifetime Affiliates
Configuration: CLIENTS_WITH_LIFE_TIME_AFFILIATES = ["tradexmastery", "instiedge"]
Behavior:
The first affiliate who refers a user is locked in permanently
All future purchases by that user credit the original affiliate
Most persistent model - cannot be changed by subsequent referral links
Use Case: Reward affiliates for long-term customer relationships, ensuring they benefit from all future purchases.
Data Priority:
Check AffiliateUserToUplineUserMapping for explicit upline assignment
Fall back to first AffiliateCommission record's affiliate
2. User-Level Affiliates
Configuration: CLIENTS_WITH_USER_LEVEL_AFFILIATES = ["tradexmastery", "demo"]
Behavior:
Uses the most recent affiliate associated with the user
Can be updated if user clicks a new referral link
Provides flexibility while still maintaining user-level tracking
Use Case: Allow users to switch affiliates, useful for partnerships or promotional campaigns.
Data Source: Most recent AffiliateCommission record for the user
3. Order-Level Affiliates (Default)
Configuration: No special configuration needed (default behavior)
Behavior:
Only tracks referral if explicitly provided in the checkout request
No persistence across purchases
Each order must include referral_id parameter
Use Case: Maximum flexibility, suitable for one-time promotions or campaigns where tracking per-order is preferred.