Skip to main content

​
Overview

Multi-step rewards let you incentivize both the customer (referrer) and their friend (referee) at different stages of the referral journey.
Examples of steps you might configure:
  • Friend creates an account
  • Friend places an order (optionally with conditions, e.g., number_of_products equals 3)
One-time steps: You can mark a step as Happens One Time in your configuration without extra metadata or custom rules.

​
What you’ll build

  • A Steps UI that renders each configured referral step (trigger, who gets rewarded, reward details).
  • The customer’s referral code/link to share.
  • The customer’s referral progress (list + counts).

​
Implementation Steps

​
1) Fetch and render the multi-step config

Get Referrals Configurations

GET /integrations/configurations/referrals
Returns the referral rule(s), including trigger and rewards.
 The configuration can be a single object (one step) or an array (multiple steps). Normalize to an array, then render each item as a step card. Example response (real-shape sample): 
{
  "referralMethod": "CustomerAndFriend",
  "eventName": "place_order",
  "steps": [
    {
      "stepName": "Step 1: Create Account",
      "eventName": "create_account",
      "customerReward": { "points": 100 },
      "friendReward": {
        "coupon": { "type": "percentage_discount", "value": 10, "expiryDate": "2025-12-31T23:59:59Z" }
      }
    },
    {
      "stepName": "Step 2: Place Order",
      "eventName": "place_order",
      "customerReward": { "points": 200 },
      "friendReward": {
        "coupon": { "type": "fixed_discount", "value": 20, "expiryDate": "2025-12-31T23:59:59Z" }
      }
    }
  ]
}
{
  "referralMethod": "CustomerAndFriend",
  "eventName": "place_order",
  "steps": [
    {
      "stepName": "Step 1: Create Account",
      "eventName": "create_account",
      "customerReward": { "points": 100 },
      "friendReward": {
        "coupon": { "type": "percentage_discount", "value": 10, "expiryDate": "2025-12-31T23:59:59Z" }
      }
    },
    {
      "stepName": "Step 2: Place Order",
      "eventName": "place_order",
      "customerReward": { "points": 200 },
      "friendReward": {
        "coupon": { "type": "fixed_discount", "value": 20, "expiryDate": "2025-12-31T23:59:59Z" }
      }
    }
  ]
}
Render guidance (what to show per step):
  • Trigger: from eventName + optional eventMetaData (e.g., place order — number_of_products equals 3).
  • Who gets rewarded: from referralMethod (e.g., CustomerAndFriend).
  • Customer reward: from customerReward (point, score, coupon) and extraReward if present (e.g., extra 500 points for every 3 events).
  • Friend reward: from friendReward (points/coupon details such as percentage, min order value, combine rules, etc.).

Get Customer

GET /integrations/configurations/referrals
Returns the customer’s referral code/link
 Fetch the customer and display referralCode and/or referralLink. 
{
  "customerId": "mike_123",
  "referralCode": "SARAH123",
  "referralLink": "https://yourwebsite.com?referralCode=SARAH123"
}
UX tip: Provide Copy buttons for both the code and the link.

​
3) Detect and propagate referral code (friend journey)

When a friend lands using a link like: 
https://yourwebsite.com?referralCode=code123
  • Read referralCode from the URL query string.
  • Store it in session/local storage (or cookie) until signup completes.
  • On friend signup, call Create/Update Customer and include referrerCode: “code123” during initial registration (within your program’s allowed window).
If referrerCode is invalid, Gameball ignores it silently and still creates the customer (no referral link formed).

​
4) Track progress (list + counts)

Show the referrer’s progress with:
  • List: GET /integrations/customers/:customerId/referrals

Get Customer Referrals

GET /integrations/customers/:customerId/referralsReturns all the referrals (pending and completed) done by the customer
Use these to display “completed vs pending” and a simple progress indicator per step.

​
Implementation checklist

  • Fetch Referrals Configurations and normalize to an array to render steps.
  • Fetch Customer and show referralCode/referralLink.
  • Capture referralCode from URL on friend visit; persist until signup.
  • On signup, send referrerCode in Create/Update Customer (initial registration window).
  • Render referrals list + counts for progress.

Referrals Configurations API

Retrieve multi-step referral rules and rewards

Create / Update Customer API

Attach referrerCode when registering friends

Validate Referrer Code API

Prevent self-referrals and invalid codes

Customer Referrals API

Monitor referral progress and counts programmatically