Referral Program API

Overview

The referral program allows customers to be linked through a unique referral_code. When a new customer signs up using a referral code, the system records this connection and triggers events that can be used for further processing.

API Endpoints

Assigning a Referral Code to a Customer

• Endpoint: PUT /api/v2.1/customers/:identifier
• Description: Allows setting a referral_code for a customer.
• Example:
  JSON

  {
    "referral_code": "ABC123"
  }
  

Using a Referral Code

• Process:
  • When a new customer signs up using referrer_code(an existing customer’s "referral_code"), the system stores the relationship.
  • Endpoint: POST /api/v2.1/customers
  • Example:
    JSON

    {
      "metadata": {},
      "identifier": "customer_001",
      "email": "johndoe@test.com",
      "loyalty_points": null,
      "name": "John Doe",
      "referrer_code": "ABC123"
    }
    

  Using a Referral Code

  • The referrer (customer whose code was used) gets an updated referred_customers property.

Retrieving Referred Customers

• Endpoint: GET /api/v2.1/customers/:identifier
• Description: Fetches customer details, including referred customers if any exist.
• Response Example:
  JSON

  {
    "referral_code": "ABC123",
    "referred_at": "2021-03-30T20:13:35.339398+01:00",
    "referred_by_id": 123,
    "referred_customers": [
      {
        "id": 0,
        "identifier": "customer_001",
        "name": "John Doe",
        "referred_at": "2021-03-30T20:13:35.339398+01:00"
      }
    ]
  }
  

Properties

Events

Two events are triggered when a customer is referred:

• customer_referred – Fired when a customer successfully refers someone.
• customer_was_referred – Fired when a customer signs up using a referral code.