Get customer loyalty information
Retrieves comprehensive loyalty information for the currently authenticated customer.
Primary use case: This is the main endpoint for displaying a customer’s loyalty dashboard. Call this endpoint when a customer views their loyalty page to show all their points, rewards, and program status.
What you’ll get:
- Current point balances (available, pending, total credited)
- Store credit balance (if applicable)
- VIP tier information and expiration
- List of rewards/discount codes
- Social media engagement tracking
- Referral statistics and link
- Account creation date
- Customer status in loyalty program
Authentication: Requires a signed-in customer. Call it through Shopify’s App Proxy on the store’s domain: the proxy signs the request and attaches the customer, so you send no API key or token. The signed-in customer’s data is returned.
Filtering rewards by status: Use the optional ‘status’ query parameter to filter rewards:
- UNUSED: Show only unused discount codes
- USED: Show only used/redeemed codes
- EXPIRED: Show only expired codes
- Multiple: “UNUSED,USED” for multiple statuses
- Omit parameter to get all rewards regardless of status
Point balance fields explained:
- availablePoints: Points customer can redeem RIGHT NOW
- pendingPoints: Points awaiting approval (e.g., from pending orders)
- creditedPoints: Approved points earned toward VIP tiers, since the VIP program’s start date or within its current evaluation period (including points since spent). Points given back for a cancelled, returned or expired reward aren’t counted again.
VIP tier information:
- currentVipTier: Name of customer’s current tier (null if not in a tier)
- vipTierExpiredAt: When tier expires (null if permanent or not in tier)
- achievableTierId: Next tier customer can reach
Social media tracking (boolean flags):
- rewardedForFacebook: Claimed Facebook like/follow points
- rewardedForInstagram: Claimed Instagram follow points
- rewardedForTwitter: Claimed Twitter follow points
- rewardedForPinterest: Claimed Pinterest follow points
- rewardedForYoutube: Claimed YouTube subscribe points
- rewardedForTiktok: Claimed TikTok follow points
- rewardedForNewsLetter: Claimed newsletter signup points
- rewardedForSms: Claimed SMS subscription points
- rewardedForCreatingAccount: Claimed account creation points
- rewardedForSharingOnFacebook: Claimed Facebook share points
- rewardedForSharingOnX: Claimed X (Twitter) share points
Referral information:
- referredCompleted: Number of successful referrals
- referralLink: Unique URL for customer to share
Customer status values:
- ACTIVE: Actively enrolled in loyalty program
- EXCLUDED: Excluded by admin
- EXCLUDED_BY_CUSTOMER: Customer opted out
Common integration patterns:
- Load loyalty dashboard: Call on page load
- After redemption: Call to get updated points and new reward
- After earning points: Call to show updated balance
- Real-time updates: Poll this endpoint or use webhooks
Performance tips:
- Cache response for 30-60 seconds on frontend
- Don’t call on every page view, only on loyalty pages
- Use status parameter to reduce response size if needed
curl --request GET \
--url https://{storeDomain}/apps/loyalty/cp/api/customer-loyaltyimport requests
url = "https://{storeDomain}/apps/loyalty/cp/api/customer-loyalty"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://{storeDomain}/apps/loyalty/cp/api/customer-loyalty', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://{storeDomain}/apps/loyalty/cp/api/customer-loyalty';
const options = {method: 'GET'};
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/customer-loyalty",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://{storeDomain}/apps/loyalty/cp/api/customer-loyalty"
req, _ := http.NewRequest("GET", url, nil)
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/customer-loyalty")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"availablePoints": 150.5,
"creditedPoints": 175.5,
"currentVipTier": "Gold",
"customerStatus": "ACTIVE",
"dob": "1990-05-15",
"pendingPoints": 25,
"referralLink": "https://store.com/referral/abc123",
"referredCompleted": 3,
"rewardedForFacebook": true,
"rewardedForInstagram": false,
"rewards": [],
"spentAmount": 299.99,
"storeCreditBalance": 15,
"vipTierExpiredAt": "2025-12-31T23:59:59Z"
}Query Parameters
Response
Customer loyalty information retrieved successfully
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 GET \
--url https://{storeDomain}/apps/loyalty/cp/api/customer-loyaltyimport requests
url = "https://{storeDomain}/apps/loyalty/cp/api/customer-loyalty"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://{storeDomain}/apps/loyalty/cp/api/customer-loyalty', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://{storeDomain}/apps/loyalty/cp/api/customer-loyalty';
const options = {method: 'GET'};
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/customer-loyalty",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://{storeDomain}/apps/loyalty/cp/api/customer-loyalty"
req, _ := http.NewRequest("GET", url, nil)
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/customer-loyalty")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"availablePoints": 150.5,
"creditedPoints": 175.5,
"currentVipTier": "Gold",
"customerStatus": "ACTIVE",
"dob": "1990-05-15",
"pendingPoints": 25,
"referralLink": "https://store.com/referral/abc123",
"referredCompleted": 3,
"rewardedForFacebook": true,
"rewardedForInstagram": false,
"rewards": [],
"spentAmount": 299.99,
"storeCreditBalance": 15,
"vipTierExpiredAt": "2025-12-31T23:59:59Z"
}