Skip to main content
Referral programs are a proven way to grow your customer base by rewarding both the referrer and the referred friend. This guide shows how to surface your referral configuration, visualize progress, and build UI that motivates sharing.

​
What Is a Referral Program?

Imagine this: A loyal customer, Sarah, loves your brand. Sarah shares her unique referral link with her friend, Mike. Mike joins using her link, and both Sarah and Mike receive exciting rewards. Sarah feels valued, and Mike gets a warm welcome.

​
How Referral Programs Work

Referral programs reward two parties:
  • Referrer (Existing Customer): Earns points, coupons, or both when friends complete a qualifying action.
  • Referred Friend (New Customer): Receives an incentive (e.g., discount coupon or bonus points) after their first action.
You can customize rewards for both sides based on your goals.

​
Key Features and Endpoints

  1. Retrieve Referral Program Configuration Use this endpoint to define how referrals are rewarded. 
    {
    "referralMethod": "CustomerAndFriend",
    "eventName": "place_order",
    "eventMetaData": {
        "name": "number_of_products",
        "operator": "equals",
        "value": "3"
    },
    "customerReward": {
        "extraReward": {
            "forEvery": 3,
            "point": 500
        },
        "point": 200
    },
    "friendReward": {
        "coupon": {
            "couponType": "Percentage",
            "discountValue": 10.0,
            "minOrderValue": 50.0,
            "expiryAfter": "2025-12-31",
            "product": "Any"
        }
    }
}
    • Referral Method: Both Sarah and Mike get rewards.
    • Customer Reward: Sarah earns 200 points plus 500 points for every 3 completed referrals.
    • Friend Reward: Mike gets a 10% coupon valid for orders over $50.
  2. Retrieve Customer Referral History Use this to display a customer’s referral progress. 
    {
    "referredFriends": [
        {
            "customerId": "cust_12345abc",
            "displayName": "John Doe",
            "email": "johndoe@company.com",
            "status": "Pending"
        },
        {
            "customerId": "cust_67890xyz",
            "displayName": "Blake Eaton",
            "email": "blake@company.com",
            "status": "Active"
        }
    ],
    "count": 2
}

​
Scenarios to Explore

Scenario 1: Mike Places His First Order
  1. Sarah shares her referral link.
  2. Mike clicks the link, registers, and places his first order of $60.
  3. Based on the configuration:
    • Mike gets a 10% coupon ($6 off).
    • Sarah earns 200 points for referring Mike.
Scenario 2: Sarah Refers Multiple Friends Sarah refers Jane and Mike. Her rewards over time:
  • Day 1: Mike registers and becomes active. Sarah earns 200 points.
  • Day 3: Jane registers but hasn’t placed an order yet (Pending).
Using the history endpoint, Sarah sees: 
{
  "referredFriends": [
    { "displayName": "Mike", "status": "Active" },
    { "displayName": "Jane", "status": "Pending" }
  ]
}

​
Visual Examples

  • Referral Popup (For New Users) A warm welcome with rewards mentioned upfront.
    Referral popup example
  • Referral History Show pending and active referrals in a neat interface.
    Referral history UI
  • Referral Sharing Widget Encourage sharing with a simple copy-and-paste link.
    Referral sharing widget

​
Implementation Tips

  • Highlight rewards prominently to drive engagement.
  • Gamify with badges or leaderboards for top referrers.
  • Track performance with analytics and iterate on rewards.