Claim Referee Incentive

cURL

curl --request POST \
  --url https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "referral_id": "jRq0X",
  "ip_address": "203.0.113.42",
  "user_agent": "<string>",
  "referee_email": "referee@example.com"
}
'

import requests

url = "https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive"

payload = {
    "referral_id": "jRq0X",
    "ip_address": "203.0.113.42",
    "user_agent": "<string>",
    "referee_email": "referee@example.com"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    referral_id: 'jRq0X',
    ip_address: '203.0.113.42',
    user_agent: '<string>',
    referee_email: 'referee@example.com'
  })
};

fetch('https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'referral_id' => 'jRq0X',
    'ip_address' => '203.0.113.42',
    'user_agent' => '<string>',
    'referee_email' => 'referee@example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive"

	payload := strings.NewReader("{\n  \"referral_id\": \"jRq0X\",\n  \"ip_address\": \"203.0.113.42\",\n  \"user_agent\": \"<string>\",\n  \"referee_email\": \"referee@example.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"referral_id\": \"jRq0X\",\n  \"ip_address\": \"203.0.113.42\",\n  \"user_agent\": \"<string>\",\n  \"referee_email\": \"referee@example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"referral_id\": \"jRq0X\",\n  \"ip_address\": \"203.0.113.42\",\n  \"user_agent\": \"<string>\",\n  \"referee_email\": \"referee@example.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "kind": "incentive",
  "incentive": {
    "code": "LL-XYA3816"
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "referee_email_required"
  }
}

{
  "error": {
    "code": "rate_limited"
  }
}

POST

headless

2025-06

{site_id}

referrals

referee_incentive

cURL

curl --request POST \
  --url https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "referral_id": "jRq0X",
  "ip_address": "203.0.113.42",
  "user_agent": "<string>",
  "referee_email": "referee@example.com"
}
'

import requests

url = "https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive"

payload = {
    "referral_id": "jRq0X",
    "ip_address": "203.0.113.42",
    "user_agent": "<string>",
    "referee_email": "referee@example.com"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    referral_id: 'jRq0X',
    ip_address: '203.0.113.42',
    user_agent: '<string>',
    referee_email: 'referee@example.com'
  })
};

fetch('https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'referral_id' => 'jRq0X',
    'ip_address' => '203.0.113.42',
    'user_agent' => '<string>',
    'referee_email' => 'referee@example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive"

	payload := strings.NewReader("{\n  \"referral_id\": \"jRq0X\",\n  \"ip_address\": \"203.0.113.42\",\n  \"user_agent\": \"<string>\",\n  \"referee_email\": \"referee@example.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"referral_id\": \"jRq0X\",\n  \"ip_address\": \"203.0.113.42\",\n  \"user_agent\": \"<string>\",\n  \"referee_email\": \"referee@example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.loyaltylion.com/headless/2025-06/{site_id}/referrals/referee_incentive")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"referral_id\": \"jRq0X\",\n  \"ip_address\": \"203.0.113.42\",\n  \"user_agent\": \"<string>\",\n  \"referee_email\": \"referee@example.com\"\n}"

response = http.request(request)
puts response.read_body

{
  "kind": "incentive",
  "incentive": {
    "code": "LL-XYA3816"
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "referee_email_required"
  }
}

{
  "error": {
    "code": "rate_limited"
  }
}

Exchange an inbound referral id for the referee incentive — a discount voucher code you can display to the referred shopper. Use this when a shopper arrives at your storefront or app with an ll_ref_id query parameter, which is how our referral links identify who referred them. The referral_id is the value of that ll_ref_id parameter. The ip_address must be the referred shopper’s own address — the one that reached your server, never your server’s — as it powers referral fraud detection. Pass referee_email whenever you know the shopper’s email. It binds the voucher to them, and it’s what allows self-referrals and referrals of existing program members to be rejected (invalid_referee). If the referrer isn’t an enrolled member, the email is required, and you’ll receive a referee_email_required error until you supply it — collect the shopper’s email and retry. It’s safe to retry: claiming again with the same referral and referee returns the same code rather than issuing a new one. To present the offer alongside the code (“Get 10% off your first order, up to $30”), use the referee_incentive object from Get Configuration, which carries localized display text and the structured discount details. When the shopper later places their first order using the voucher, the referral completes automatically — the shopper is linked to their referrer and your referral rule triggers. See the referrals guide for the end-to-end flow.

Authorizations

Authorization

string

header

required

An API key linked to a Program in LoyaltyLion, with a set of permissions (scopes). API keys can be created manually, or acquired through an OAuth2 flow. The API key should be provided as a Bearer token in the Authorization header

Path Parameters

site_id

number

required

Your LoyaltyLion Site ID

Body

application/json

Body

referral_id

string

required

The referral the shopper arrived with. This is the value of the ll_ref_id query parameter on the URL the referral link redirects to

Minimum string length: 1

Example:

"jRq0X"

ip_address

required

The IP address of the shopper claiming the incentive — the one that reached your server, not your server's own. It is what detects referral fraud when the program restricts referrals to distinct IP addresses, and it is the bucket we would rate-limit an individual shopper on

Send a single address. A forwarded-for list is rejected: take the client entry from it yourself

Pattern: ^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$

Example:

"203.0.113.42"

user_agent

string | null

required

The user agent of the shopper claiming the incentive, recorded alongside the referral for fraud analysis. Send null where the caller genuinely has none, such as a native mobile app

referee_email

string<email>

The email address of the shopper claiming the incentive. Pass it whenever you know it: it binds the voucher to that shopper, and it is what lets us reject a shopper who is referring themselves or who is already a member of the program

It is only required when the referrer is not enrolled in the program. A request that needs it and omits it is rejected with referee_email_required, so you can retry with the address once you have collected it

Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

Example:

"referee@example.com"

Response

The incentive was claimed. Repeating the request with the same referral_id and referee_email returns the same code. kind discriminates this from any further success outcome added later — switch on it rather than assuming a code is present

kind

string

required

Allowed value: "incentive"

incentive

object

required

Show child attributes

Headless API

Guides

Resources

Claim Referee Incentive

Authorizations

Path Parameters

Body

Response