Referrals
Referral Overview
The Phoenix Referral system helps you grow users through invitation-based rewards and affiliate-style commissions.
It supports three referral models:
- Basic Referral - One user invites another and both can receive rewards.
- Affiliate - Approved affiliates earn ongoing rewards from referred user activity.
- Hierarchical Affiliate - Optional multi-level affiliate structure for parent/child affiliate networks.
What Is a Referral System?
A referral system links a referrer (the inviter) to a referee (the invited user), then applies rewards when qualifying conditions are met.
Typical lifecycle:
- A user gets or creates a referral code.
- A new user applies that code.
- The system confirms eligibility and attribution.
- Rewards and/or commissions are granted.
Key Concepts
Referral Codes
A short, shareable code users can send to friends. Codes can be limited by:
- usage count
- activation status
- expiration date
Referral Campaigns
Campaigns define reward behavior for a period or promotion, for example:
- welcome bonus campaign
- seasonal growth campaign
- high-value acquisition campaign
Attribution
Attribution is the relationship between inviter and invited user. A user is typically attributed once for a given referral program.
Referral Status
Common statuses include:
- pending - code applied, waiting for qualification
- qualified - condition met
- rewarded - reward completed
Affiliate Commissions
In affiliate mode, commissions can be granted repeatedly based on qualifying activity.
How Referrals Work
Basic Referral Flow
- Referrer shares a code.
- Referee applies the code.
- System tracks qualification.
- Rewards are applied for referrer and/or referee.
Affiliate Flow
- Affiliate account is approved.
- Affiliate shares code.
- Referees are attributed to that affiliate.
- Commission records are generated as qualifying activity happens.
Hierarchical Flow
- Affiliates can be connected in parent/child structure.
- Commissions can be distributed across multiple levels.
- Downline visibility is available via query APIs.
What You Can Do from Client Integrations
- create and manage referral codes
- apply referral codes
- check referral attribution and status
- view affiliate status
- view affiliate commission history
- view affiliate downline (if enabled)
Next Steps
- Creating Referral Programs - Learn how to set up referral systems
- Querying Results - Learn how to retrieve referral data