Accept referral offer (POST)
Accepts a referral for a friend: records that the person with email was referred by the customer who owns token.
No signed-in customer is needed. This endpoint also works for a shopper who isn’t signed in: the friend is
identified by email, not by a session. If the store has no customer with that email, a Shopify customer is created
for it. The request still has to come through the App Proxy, with X-Requested-With: XMLHttpRequest.
Where the token comes from. It’s the last part of the referrer’s referralLink, which Get customer loyalty
details in the Admin API returns. When a friend opens that link, it redirects to the store’s primary domain with
appstle_referral=true and appstle_referral_code={token} in the query string. On a theme with the Appstle Loyalty
app embed on, the loyalty widget reads the token and calls this endpoint itself. Call it yourself only from a
referral page you build.
Request body: token and email, both required.
Example (JavaScript on the referral landing page):
const token = new URLSearchParams(window.location.search).get('appstle_referral_code');
const response = await fetch('/apps/loyalty/cp/api/referral-rules/accept-offer', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Requested-With': 'XMLHttpRequest' },
body: JSON.stringify({ token, email: 'friend@example.com' })
});
const result = await response.json();
Result. A new referral returns 201 with status SUCCESS and message “Referral accepted successfully.”.
existingCustomer is true when the email already belonged to a customer of the store. id is always empty.
discountCode is the friend’s own reward code when the friend got a discount code on acceptance and Appstle support
has turned on returning it for the store; otherwise it’s empty. It’s never the referrer’s code. Reward codes are
emailed to both customers either way, only while the store’s app embed is on. Rewards
given on acceptance show up in each customer’s loyalty data (Get customer loyalty details in the Admin API).
When each customer is rewarded follows the merchant’s referral settings. With When referred friend accepts the invitation, both are rewarded as soon as the friend accepts. With the purchase-based options, both are rewarded after the friend’s qualifying purchase, unless the merchant chooses to reward one of them on acceptance instead. A reward can be points, a discount code or store credit.
Failures return 400 with status FAILED and a message. Two of them also set errorKey, which stays the same
when the message text changes:
SELF_REFERRAL(“You cannot refer yourself.”):emailbelongs to the customer who ownstoken.ALREADY_REFERRED(“Already have an account or already referred.”):emailhas already accepted a referral at this store. An existing account alone doesn’t cause it; seeexistingCustomer.
Treat any other errorKey value as a generic failure. The merchant’s own text for these two errors is in the widget
labels selfReferralErrorLabel and alreadyReferredErrorLabel.
These failures have no errorKey:
- “Invalid request, token not found.”: the token doesn’t exist at this store, or the store’s referral program isn’t active.
- “Referring customer is restricted from referring”, “Referring customer isn’t allowed to refer”, “Customer is Restricted from being referred” and “Customer isn’t Allowed for referring”: the merchant’s customer-tag rules for referrals refuse the referrer or the friend.
- “An error occurred while processing the request.”: the email address or the referrer was refused to prevent abuse.
A missing or empty token or email returns a different 400 body: an application/problem+json error whose
title is “A referral token or email should not empty” and whose errorKey is the string "null".
curl --request POST \
--url https://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer \
--header 'Content-Type: application/json' \
--data '
{
"email": "friend@example.com",
"token": "abc123def456ghij"
}
'import requests
url = "https://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer"
payload = {
"email": "friend@example.com",
"token": "abc123def456ghij"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({email: 'friend@example.com', token: 'abc123def456ghij'})
};
fetch('https://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer';
const options = {
method: 'POST',
headers: {'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://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer",
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"
],
]);
$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://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer"
payload := strings.NewReader("{\n \"email\": \"friend@example.com\",\n \"token\": \"abc123def456ghij\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
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": null,
"errorKey": null,
"existingCustomer": false,
"id": null,
"message": "Referral accepted successfully.",
"status": "SUCCESS"
}{
"discountCode": null,
"errorKey": "ALREADY_REFERRED",
"existingCustomer": null,
"id": null,
"message": "Already have an account or already referred.",
"status": "FAILED"
}Body
Response
Referral offer accepted successfully
curl --request POST \
--url https://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer \
--header 'Content-Type: application/json' \
--data '
{
"email": "friend@example.com",
"token": "abc123def456ghij"
}
'import requests
url = "https://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer"
payload = {
"email": "friend@example.com",
"token": "abc123def456ghij"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({email: 'friend@example.com', token: 'abc123def456ghij'})
};
fetch('https://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer';
const options = {
method: 'POST',
headers: {'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://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer",
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"
],
]);
$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://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer"
payload := strings.NewReader("{\n \"email\": \"friend@example.com\",\n \"token\": \"abc123def456ghij\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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://{storeDomain}/apps/loyalty/cp/api/referral-rules/accept-offer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
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": null,
"errorKey": null,
"existingCustomer": false,
"id": null,
"message": "Referral accepted successfully.",
"status": "SUCCESS"
}{
"discountCode": null,
"errorKey": "ALREADY_REFERRED",
"existingCustomer": null,
"id": null,
"message": "Already have an account or already referred.",
"status": "FAILED"
}