> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Step Referrals (Custom Web UI)

> Display and track multi-step referral progress with Gameball APIs using your own UI.

# 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)

<img src="https://mintcdn.com/gameball/j0SE7da_0_5850iq/images/multistepreferal.gif?s=2a0c7226dc450df9c87509cdbde5efc1" className="mx-auto" style={{ width:"100%" }} width="1896" height="922" data-path="images/multistepreferal.gif" />

<Note>
  **One-time steps:** You can mark a step as **Happens One Time** in your configuration without extra metadata or custom rules.
</Note>

***

## 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.

<img src="https://mintcdn.com/gameball/j0SE7da_0_5850iq/images/referalCodeLinkUI.png?fit=max&auto=format&n=j0SE7da_0_5850iq&q=85&s=0a0198d8770263911bae7266a13680f9" className="mx-auto" style={{ width:"50%" }} width="806" height="832" data-path="images/referalCodeLinkUI.png" />

* The customer’s **referral progress** (list + counts).

<img src="https://mintcdn.com/gameball/j0SE7da_0_5850iq/images/referalStatus.png?fit=max&auto=format&n=j0SE7da_0_5850iq&q=85&s=37a9b35ca6227e001ce163e9bddf630c" className="mx-auto" style={{ width:"60%" }} width="804" height="458" data-path="images/referalStatus.png" />

***

## Implementation Steps

### 1) Fetch and render the multi-step config

<Card title="Get Referrals Configurations" icon="gear-code" horizontal href="/api-reference/configurations/program-configurations/referral-settings">
  `GET /integrations/configurations/referrals`\
  Returns the referral rule(s), including trigger and rewards.
</Card>

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):**

```json theme={null}
{
  "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.).

### **2) Show the customer’s referral code/link**

<Card title="Get Customer" icon="head-side" horizontal href="/api-reference/customers/management/get-customer">
  `GET /integrations/configurations/referrals`\
  Returns the customer's referral code/link
</Card>

Fetch the customer and display referralCode and/or referralLink.

```json theme={null}
{
  "customerId": "mike_123",
  "referralCode": "SARAH123",
  "referralLink": "https://yourwebsite.com?referralCode=SARAH123"
}
```

<Tip>
  **UX tip:** Provide **Copy** buttons for both the code and the link.
</Tip>

### **3) Detect and propagate referral code (friend journey)**

When a friend lands using a link like:

```bash theme={null}
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**](/api-reference/customers/management/create-customer) and include `referrerCode`: "code123" **during initial registration** (within your program’s allowed window).

<Warning>
  If `referrerCode` is invalid, Gameball ignores it silently and still creates the customer (no referral link formed).
</Warning>

### **4) Track progress (list + counts)**

<img src="https://mintcdn.com/gameball/j0SE7da_0_5850iq/images/referalProgress.png?fit=max&auto=format&n=j0SE7da_0_5850iq&q=85&s=1b449bb4d68ddcea85b2bf9d3e3d738c" className="mx-auto" style={{ width:"100%" }} width="2160" height="1568" data-path="images/referalProgress.png" />

Show the referrer’s progress with:

* **List:** GET /integrations/customers/:customerId/referrals

<Card title="Get Customer Referrals" icon="people-group" horizontal href="/api-reference/customers/progress/get-customer-referrals">
  `GET /integrations/customers/:customerId/referrals`

  Returns all the referrals (pending and completed) done by the customer
</Card>

* **Counts:** GET /integrations/customers/:customerId/referrals/count (e.g., completed, pending, total)

  <Card title="Get Customer Referrals count" icon="hashtag" horizontal href="/api-reference/customers/progress/get-customer-referrals-count">
    `GET /integrations/customers/:customerId/referrals/count`

    Returns the total count of referees referred by a customer
  </Card>

<Tip>
  Use these to display “completed vs pending” and a simple progress indicator per step.
</Tip>

***

## **Implementation checklist**

<Check>
  * 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.
</Check>

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Referrals Configurations API" icon="gear-code" href="/api-reference/configurations/program-configurations/referral-settings">
    Retrieve multi-step referral rules and rewards
  </Card>

  <Card title="Create / Update Customer API" icon="user-plus" href="/api-reference/customers/management/create-customer">
    Attach `referrerCode` when registering friends
  </Card>

  <Card title="Validate Referrer Code API" icon="shield-check" href="/api-reference/customers/management/validate-referrer-code">
    Prevent self-referrals and invalid codes
  </Card>

  <Card title="Customer Referrals API" icon="people-group" href="/api-reference/customers/progress/get-customer-referrals">
    Monitor referral progress and counts programmatically
  </Card>
</CardGroup>