Referrals

Accept a referral invite

Records that a friend accepted a customer’s referral invite. This is the Public API equivalent of the storefront widget’s referral claim, for headless storefronts that can’t use the theme widget.

The headless referral flow:

Get the referring customer’s link from GET /api/external/customer-loyalty (referralLink).
The link lands on https://<store>/?appstle_referral=true&appstle_referral_code=<TOKEN>. Read appstle_referral_code from the landing URL, collect the friend’s email, and send both here.
For order-based referral programs, the referral completes when the friend places a qualifying order with that same email. No further API call is needed.
Show the referring customer’s referrals with GET /api/external/customer-referrals.

Call this from your server. Never expose your API key in browser code.

Headless stores: order-based referral rewards and referral emails need the Appstle app embed enabled in the store’s published Online Store theme, even when shoppers never see that theme.

What happens:

The same checks as the storefront widget apply: invalid token, self-referral, an email that was already referred, an inactive referral program, and the referral program’s customer-tag restrictions all return 400.
On success, a PENDING referral is created and any reward configured to be given on acceptance is issued.
Reward discount codes are not returned in the response (discountCode is always empty). They’re emailed to each customer, and only when the Appstle app embed is enabled in the store’s theme.
existingCustomer is true when the email already belongs to a store customer.
When no referral program is active, the 400 response’s message reads “Invalid request, token not found.”

POST

api

external

referral-accept

Accept a referral invite

curl --request POST \
  --url https://loyalty-admin.appstle.com/api/external/referral-accept \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "email": "friend@example.com",
  "token": "abc123def456ghij"
}
'

import requests

url = "https://loyalty-admin.appstle.com/api/external/referral-accept"

payload = {
    "email": "friend@example.com",
    "token": "abc123def456ghij"
}
headers = {
    "X-API-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({email: 'friend@example.com', token: 'abc123def456ghij'})
};

fetch('https://loyalty-admin.appstle.com/api/external/referral-accept', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://loyalty-admin.appstle.com/api/external/referral-accept';
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({email: 'friend@example.com', token: 'abc123def456ghij'})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://loyalty-admin.appstle.com/api/external/referral-accept",
  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([
    'email' => 'friend@example.com',
    'token' => 'abc123def456ghij'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <x-api-key>"
  ],
]);

$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://loyalty-admin.appstle.com/api/external/referral-accept"

	payload := strings.NewReader("{\n  \"email\": \"friend@example.com\",\n  \"token\": \"abc123def456ghij\"\n}")

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

	req.Header.Add("X-API-Key", "<x-api-key>")
	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))

}

require 'uri'
require 'net/http'

url = URI("https://loyalty-admin.appstle.com/api/external/referral-accept")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"friend@example.com\",\n  \"token\": \"abc123def456ghij\"\n}"

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

{
  "discountCode": "<string>",
  "errorKey": "<string>",
  "existingCustomer": true,
  "id": 123,
  "message": "<string>",
  "status": "SUCCESS"
}

{
  "discountCode": "<string>",
  "errorKey": "<string>",
  "existingCustomer": true,
  "id": 123,
  "message": "<string>",
  "status": "SUCCESS"
}

Headers

X-API-Key

string

required

API key for authentication

Body

application/json

The referral token from the link (appstle_referral_code) and the friend's email

string

required

Email address of the friend accepting the referral

Example:

"friend@example.com"

token

string

required

Referral token: the last part of the referrer's referralLink

Example:

"abc123def456ghij"

Response

Referral accepted

discountCode

string

Always empty. Reward codes are emailed to the customers instead.

errorKey

string

Stable code for some failures: SELF_REFERRAL or ALREADY_REFERRED. Empty on success and on other failures.

existingCustomer

boolean

On success, true when the email already belonged to a customer of the store

integer<int64>

Always empty. The referral record ID isn't returned.

message

string

Result message in English, such as "Referral accepted successfully."

status

enum<string>

SUCCESS when the referral was accepted, FAILED when it was refused

Available options:

SUCCESS,

FAILED

Accept a referral invite

curl --request POST \
  --url https://loyalty-admin.appstle.com/api/external/referral-accept \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "email": "friend@example.com",
  "token": "abc123def456ghij"
}
'

import requests

url = "https://loyalty-admin.appstle.com/api/external/referral-accept"

payload = {
    "email": "friend@example.com",
    "token": "abc123def456ghij"
}
headers = {
    "X-API-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({email: 'friend@example.com', token: 'abc123def456ghij'})
};

fetch('https://loyalty-admin.appstle.com/api/external/referral-accept', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://loyalty-admin.appstle.com/api/external/referral-accept';
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({email: 'friend@example.com', token: 'abc123def456ghij'})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://loyalty-admin.appstle.com/api/external/referral-accept",
  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([
    'email' => 'friend@example.com',
    'token' => 'abc123def456ghij'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <x-api-key>"
  ],
]);

$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://loyalty-admin.appstle.com/api/external/referral-accept"

	payload := strings.NewReader("{\n  \"email\": \"friend@example.com\",\n  \"token\": \"abc123def456ghij\"\n}")

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

	req.Header.Add("X-API-Key", "<x-api-key>")
	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))

}

require 'uri'
require 'net/http'

url = URI("https://loyalty-admin.appstle.com/api/external/referral-accept")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"friend@example.com\",\n  \"token\": \"abc123def456ghij\"\n}"

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

{
  "discountCode": "<string>",
  "errorKey": "<string>",
  "existingCustomer": true,
  "id": 123,
  "message": "<string>",
  "status": "SUCCESS"
}

{
  "discountCode": "<string>",
  "errorKey": "<string>",
  "existingCustomer": true,
  "id": 123,
  "message": "<string>",
  "status": "SUCCESS"
}

Get started

Backend integration

Storefront integration

Partner integration

Resources

Admin API

Storefront API

Accept a referral invite

Headers

Body

Response