Skip to main content

Referral Program in Sailplay

The referral program allows clients to invite friends to the loyalty program and receive rewards. Two parties are involved in the scenario:

  • Referrer — the client who invites.
  • Referral — the client who registers/performs actions upon invitation.

The reward (bonus points or other benefits) can be accrued to both the referrer and the referral — depending on the promotion/scenario settings in Sailplay.

What you will get after implementation
  • The client sees their referral code and shares it.
  • A new client registers or enters the code during purchase.
  • Events/tags are recorded in the profiles of both clients, and (with configured mechanics) bonuses are accrued.

How it Looks in Events and Tags​

After successful referral registration, the following appear in the referral's profile:

  • Event "Client was invited by 'First Name Last Name (inviter)'"
  • Tag "Friend registration by invitation"

In the referrer's profile, the following appear:

  • Event "Invited client 'First Name Last Name (invited friend)'"
  • Tag "Client invited a friend"

When the referral makes a purchase (and the mechanic conditions are met), events may be displayed in the cards:

  • For the referrer — "Referral made a purchase"
  • For the referral — "Confirmation of purchase by referral"

Referral Promocode​

The program uses a unique referral promocode — each client registered in Sailplay receives an individual code.

How to Get a Client's Promocode​

Retrieve client data using the method:

  • /api/v2/users/info/

The promocode is returned in the response field:

  • referral_promocode

How to Show the Promocode to the Client​

In the interface (dashboard/mobile app/website):

  • Display the referral_promocode value in the client profile.

In communications (email/SMS/push):

  • Insert the referral code into messages via a variable (see the "Client Variables" section).

A referral link between a referrer and a referral can be created in two main ways.

Important

The actual logic of accruals (for registration, for purchase, for purchase confirmation, etc.) is set on the Sailplay side through promotions/scenarios. Integration is responsible for the correct transmission of the referral code/identifiers.

Method 1. Referral Code During Purchase​

The referral enters the referrer's promocode at the time of order placement.

1) Cart Calculation (calc)​

At the checkout stage, send a request for promotion calculation:

  • /api/v2/marketing-actions/calc/

Pass the referrer's promocode in the promocodes parameter.

Example (cURL):

curl --request POST \
  --url https://api.sailplay.net/api/v2/marketing-actions/calc/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data order_num=171 \
  --data 'cart={"1":{"sku":"1","price":1000,"quantity":1},"2":{"sku":"2","price":300,"quantity":3}}' \
  --data user_phone=70001234567 \
  --data 'promocodes=["<referral_promocode>"]'

2) Purchase Creation (new)​

After placing the order, create a purchase:

  • /api/v2/purchases/new/

The parameters are similar (including promocodes).

Example (cURL):

curl --request POST \
  --url https://api.sailplay.net/api/v2/purchases/new/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data order_num=171 \
  --data 'cart={"1":{"sku":"1","price":1000,"quantity":1},"2":{"sku":"2","price":300,"quantity":3}}' \
  --data user_phone=70001234567 \
  --data 'promocodes=["<referral_promocode>"]'
Important

A referral link during purchase creation is formed only if a promotion is configured in the Sailplay dashboard for the "Referral Promocodes" system group and the promocode is applied in the purchase.

The link is created at the moment of referral registration: you create a client and simultaneously pass the referrer's data.

Use the client creation method:

  • /api/v2/users/add/

Pass the referral's identifiers (phone/email/origin_user_id) and one of the referrer's data sets:

  • referrer_promocode — the referrer's referral code
    and/or
  • referrer_phone
  • referrer_email
  • referrer_origin_user_id

This approach is convenient for "invitation links," where you fix the referrer's promocode/identifier in advance and pass it when registering the referral.

Recommendation

If you use an invite-link, try to fix the referral promocode (the most convenient for transmission and storage on the frontend), or one stable referrer identifier.

Displaying Referral Program Data via Client History​

To see referral events in history, request client information using the method:

  • /api/v2/users/info/

and pass the parameter:

  • history=1

Example: history for a referral​

An entry like this may appear in the referral's history:

{
  "action": "manual_change_referrer",
  "user_name": "First Name Last Name",
  "action_date": "2023-11-17T11:52:43.121",
  "user_id": 123456789,
  "name": "Invited purchase"
}

Example: history for a referrer​

An entry like this may appear in the referrer's history:

{
  "action": "manual_change_referred",
  "user_name": "First Name Last Name",
  "action_date": "2023-11-17T11:52:43.121",
  "user_id": 987654321,
  "name": "For inviting a friend"
}

Example: bonus accruals (if configured)​

If accrual of points to the referrer/referral is configured, entries may appear in the history:

For the referrer:

{
  "action": "referral",
  "action_date": "2023-11-17T14:38:54.021",
  "is_completed": true,
  "points_delta": 1000,
  "name": "For registration by invitation"
}

For the referral:

{
  "action": "referred",
  "action_date": "2023-11-17T14:38:54.109",
  "is_completed": true,
  "points_delta": 2000,
  "name": "For inviting a friend"
}

Number of Invited Friends​

Summary information on the number of invited clients is stored in the "Number of invited friends" system tag.

To get the value, request the client's tag list using the method:

  • /api/v2/users/tags/list/

The number of friends invited by the client will be in the fire_count parameter.

Example (cURL):

curl --request GET \
  --url https://api.sailplay.net/api/v2/users/tags/list/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data user_phone=17784604 \
  --data 'tags=["Number of invited friends"]' \