Referral API - Loyalty
Endpoints for managing referral programs - validating codes, tracking stats, and applying referrals for the Loyalty API.
/api/v1/loyalty/referrals/
Referral Flow
Here's how the referral system works:
Referrer Shares Code
Existing member shares their unique referral code with friends.
Validate Code
When new user enters code, validate it using /referrals/validate-code.
Apply Referral
After new user registers, apply the referral via /referrals/apply.
Bonus Points Awarded
Both referrer and referee receive their configured bonus points.
Get Referral Stats
/api/v1/loyalty/cards/{card_id}/referral-stats
Get referral statistics for a card including total, successful, and pending referrals.
Use Cases
- Display referral program metrics on a dashboard
- Track campaign effectiveness
- Monitor referral trends over time
Response
{
"success": true,
"data": {
"stats": {
"total_referrals": 150,
"successful_referrals": 120,
"pending_referrals": 30,
"conversion_rate": 80.0
},
"period": "30d"
}
}List Top Referrers
/api/v1/loyalty/cards/{card_id}/referrers
Get list of top referrers for a card, sorted by successful referrals.
Use Cases
- Create a referral leaderboard
- Identify brand ambassadors
- Reward top performers
Query Parameters
limit=10
period=30d
limit (integer, optional) - Number of results (default: 10)
period (string, optional) - Period: 7d, 30d, 90d, all
Response
{
"success": true,
"data": {
"referrers": [
{
"member_id": 123,
"name": "Ahmed Ben Ali",
"email": "ahmed@example.com",
"total_referrals": 25,
"successful_referrals": 22
}
],
"total": 10
}
}Get Referrer's Referrals
/api/v1/loyalty/cards/{card_id}/referrers/{member_id}/referrals
Get all referrals made by a specific member.
URL Parameters:
card_id (integer, required) - The card ID
member_id (integer, required) - The referrer member ID
Response
{
"success": true,
"data": {
"referrals": [
{
"id": 1001,
"referee_name": "Tarek Fatmi",
"referee_email": "fatmi@example.com",
"status": "completed",
"bonus_points": 50,
"created_at": "2025-01-15T10:30:00Z"
}
],
"total": 22
}
}Validate Referral Code
/api/v1/loyalty/referrals/validate-code
Check if a referral code is valid for a specific card.
Validate Before Applying
Always validate codes before applying them to provide immediate feedback to users.
Request Body
{
"referral_code": "AHMED2024",
"card_id": 5
}
referral_code (string, required) - Referral code to validate
card_id (integer, required) - Card ID
Response
{
"success": true,
"data": {
"is_valid": true,
"referrer": {
"id": 123,
"name": "Ahmed Ben Ali",
"bonus_info": {
"referrer_bonus": 50,
"referee_bonus": 25
}
}
}
}Apply Referral
/api/v1/loyalty/referrals/apply
Apply a referral code to a new member and award bonus points to both parties.
One-Time Application
Referrals can only be applied once per member. Subsequent attempts will return an error.
Request Body
{
"referral_code": "AHMED2024",
"card_id": 5,
"referee_member_id": 456
}
referral_code (string, required) - Referral code
card_id (integer, required) - Card ID
referee_member_id (integer, required) - New member's ID
Response
{
"success": true,
"message": "Referral applied successfully",
"data": {
"referral": {
"id": 1001,
"referrer_id": 123,
"referee_id": 456,
"referrer_bonus": 50,
"referee_bonus": 25,
"created_at": "2025-01-20T14:30:00Z"
}
}
}