Redeem customer loyalty points
Allows the authenticated customer to redeem their loyalty points for rewards.
Redemption flow:
- Customer selects a reward from available options
- Frontend calls this endpoint with redeemRuleId
- System validates customer has sufficient points
- Points are deducted from available balance
- Discount code is created in Shopify
- Reward record is created with status “UNUSED”
- Transaction is logged
- Updated loyalty info is returned
- Customer receives discount code to use at checkout
Request body fields:
- redeemRuleId: ID of reward to redeem (required) Get available options from GET /loyalty/cp/api/customer-loyalty
- points: Number of points to spend (DYNAMIC_DISCOUNT rewards only) Required for a DYNAMIC_DISCOUNT reward: the customer chooses how many points to spend and gets the rule’s discount for every redeemPoints points Ignored for every other reward type (STORE_CREDIT, DISCOUNT_CODE, PRODUCT_DISCOUNT, COLLECTION_DISCOUNT, FREE_PRODUCT, FREE_SHIPPING): they spend the rule’s own redeemPoints and give its fixed reward, so a customer can’t choose how many points to turn into store credit
- variantId: For a FREE_PRODUCT or PRODUCT_DISCOUNT reward, the id of the product or variant the customer picked, from the rule’s productData (optional) For a FREE_PRODUCT reward that lists a whole product, the id of one of that product’s variants is also accepted, and the code still covers the whole product Any other id returns 400 “Product isn’t eligible for discount.”
Authentication:
Requires a signed-in customer. Call it through Shopify’s App Proxy on the store’s domain with the X-Requested-With: XMLHttpRequest header: the proxy signs the request and attaches the customer, so you send no API key or token.
The signed-in customer is the one redeeming points.
Cannot redeem points on behalf of another customer.
Validation checks:
- Customer is authenticated
- Customer has sufficient availablePoints
- Redemption rule exists and is active
- Customer is enrolled in loyalty program
- For a DYNAMIC_DISCOUNT reward, points is positive and within the rule’s minimum and maximum
- The reward is within its dates, offered to this customer and under its redeem limits
What happens to points:
- Deducted from availablePoints immediately
- Recorded as a DEBIT point transaction with transactionRule REDEEM_RULE
- A repeated call spends the points again: disable your redeem button while a call is in flight
- An unused discount code can be returned for its points with
POST /loyalty/cp/api/return-reward/{rewardId}, if the store allows returns - A customer the merchant excluded, or who opted out, gets 200 and no new reward
Discount code generation:
- For discounts: Creates Shopify discount code
- Code is unique per customer
- Has expiry date if configured
- Minimum purchase amount if configured
- Product/collection restrictions if configured
Store credit rewards:
- Adds value to storeCreditBalance instead of creating discount code
- Can be used as payment method at checkout
- Managed separately from Shopify discount codes
Error scenarios:
- Insufficient points: availablePoints is lower than the required points
- Invalid rule: redeemRuleId is missing, doesn’t exist or is inactive
- Not eligible: the reward is limited to other customers, is outside its dates or is over a redeem limit
- Customer not enrolled: Must enroll first
- Redeem already in progress: another redeem for the same customer is still running
- System error: Shopify API failure, discount code creation failure
Best practices:
- Check availablePoints before showing redemption options
- Display point cost clearly to customer
- Show expected reward (discount %, amount, etc.)
- Handle errors gracefully with clear messages
- After success, show discount code prominently
- Provide copy-to-clipboard functionality for code
- Explain when/how to use the discount code
Example response handling:
// After successful redemption
const response = await redeemPoints(ruleId);
// rewards is newest first, so the new reward is rewards[0]
const newReward = response.rewards[0];
// Display to customer
showDiscountCode(newReward.discountCode, newReward.expireDate);
Common UI flow:
- Display available redemption options with point costs
- Customer clicks “Redeem”
- Show confirmation dialog with point cost
- Call this endpoint
- On success: Show discount code in modal/banner
- Update points display with new balance
- Add code to “My Rewards” list
curl --request POST \
--url https://{storeDomain}/apps/loyalty/cp/api/redeem-points \
--header 'Content-Type: application/json' \
--data '
{
"redeemRuleId": 5
}
'import requests
url = "https://{storeDomain}/apps/loyalty/cp/api/redeem-points"
payload = { "redeemRuleId": 5 }
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({redeemRuleId: 5})
};
fetch('https://{storeDomain}/apps/loyalty/cp/api/redeem-points', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://{storeDomain}/apps/loyalty/cp/api/redeem-points';
const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({redeemRuleId: 5})
};
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/redeem-points",
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([
'redeemRuleId' => 5
]),
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/redeem-points"
payload := strings.NewReader("{\n \"redeemRuleId\": 5\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/redeem-points")
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 \"redeemRuleId\": 5\n}"
response = http.request(request)
puts response.read_body{
"availablePoints": 4798.24,
"creditedPoints": 26272.41,
"currentVipTier": "Gold",
"customerStatus": "ACTIVE",
"dob": null,
"pendingPoints": 0,
"referralLink": "https://referral.appstle.com/YOUR_REFERRAL_CODE",
"referredCompleted": 3,
"rewards": [
{
"createAt": "2026-11-11T14:45:48.74289Z",
"description": "$5.00 off your order",
"discountCode": "AL_EXAMPLE12345678",
"expireDate": null,
"id": 137994,
"orderName": null,
"pointRedeemRuleId": 8853,
"rewardType": "DISCOUNT_CODE",
"status": "UNUSED",
"usedAt": null
}
],
"spentAmount": 46,
"storeCreditBalance": 10,
"storeCreditCurrency": "USD",
"vipTierExpiredAt": null
}{
"message": "error.",
"params": "",
"status": 400,
"title": "Points not available",
"type": "https://appstle.com/problem/problem-with-message"
}{
"detail": "Invalid authentication",
"status": 401
}Body
Point redemption request details including redeem rule ID, points to redeem, and optional variant ID for product rewards
Customer's email address. Alternative to customerId for identifying the customer. Provide either customerId OR customerEmail, not both. Must be a valid email address that exists in your Shopify store. Example: customer@example.com
"customer@example.com"
Number of points to spend. Only DYNAMIC_DISCOUNT rewards use it: the customer chooses how many points to spend and gets the rule's discount for every redeemPoints points. Required and must be positive for those rewards, and the customer must have at least this many available points. Every other reward type (STORE_CREDIT, DISCOUNT_CODE, PRODUCT_DISCOUNT, COLLECTION_DISCOUNT, FREE_PRODUCT, FREE_SHIPPING) ignores it and spends the rule's own redeemPoints for its fixed reward. Example: 100.0
100
For a FREE_PRODUCT or PRODUCT_DISCOUNT reward, the id of the product or variant the customer picked, from the rule's productData. Optional. For a FREE_PRODUCT reward that lists a whole product, the id of one of that product's variants is also accepted, and the code still covers the whole product. Any other id returns 400. Example: 12345678
12345678
Response
Points redeemed successfully, returns updated customer loyalty information with new reward
The customer's short referral link, on https://referral.appstle.com/ or the merchant's custom referral domain. Its last part is the customer's referral token, which Accept referral offer takes as token. The link redirects to the store's primary domain with appstle_referral=true and appstle_referral_code={token} in the query string.
"https://referral.appstle.com/abc123def456ghij"
curl --request POST \
--url https://{storeDomain}/apps/loyalty/cp/api/redeem-points \
--header 'Content-Type: application/json' \
--data '
{
"redeemRuleId": 5
}
'import requests
url = "https://{storeDomain}/apps/loyalty/cp/api/redeem-points"
payload = { "redeemRuleId": 5 }
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({redeemRuleId: 5})
};
fetch('https://{storeDomain}/apps/loyalty/cp/api/redeem-points', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://{storeDomain}/apps/loyalty/cp/api/redeem-points';
const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({redeemRuleId: 5})
};
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/redeem-points",
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([
'redeemRuleId' => 5
]),
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/redeem-points"
payload := strings.NewReader("{\n \"redeemRuleId\": 5\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/redeem-points")
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 \"redeemRuleId\": 5\n}"
response = http.request(request)
puts response.read_body{
"availablePoints": 4798.24,
"creditedPoints": 26272.41,
"currentVipTier": "Gold",
"customerStatus": "ACTIVE",
"dob": null,
"pendingPoints": 0,
"referralLink": "https://referral.appstle.com/YOUR_REFERRAL_CODE",
"referredCompleted": 3,
"rewards": [
{
"createAt": "2026-11-11T14:45:48.74289Z",
"description": "$5.00 off your order",
"discountCode": "AL_EXAMPLE12345678",
"expireDate": null,
"id": 137994,
"orderName": null,
"pointRedeemRuleId": 8853,
"rewardType": "DISCOUNT_CODE",
"status": "UNUSED",
"usedAt": null
}
],
"spentAmount": 46,
"storeCreditBalance": 10,
"storeCreditCurrency": "USD",
"vipTierExpiredAt": null
}{
"message": "error.",
"params": "",
"status": 400,
"title": "Points not available",
"type": "https://appstle.com/problem/problem-with-message"
}{
"detail": "Invalid authentication",
"status": 401
}