Add points to customer account
Manually adds loyalty points to a customer’s account.
Common use cases:
- Grant bonus points for special promotions
- Compensate customers for issues or complaints
- Award points for actions tracked in external systems
- Bulk point adjustments during migrations
- Manual loyalty program adjustments
Request body fields:
- customerId OR customerEmail: Identify the customer (required, provide one)
- points: Number of points to add (required, must be greater than 0)
- note: Description/reason for points addition (optional but recommended)
- earnRuleId: Earn rule to record the points under (optional). It must exist, be active and be within its scheduled dates, or the request fails with 400
How it works:
- Finds the customer in your store’s loyalty customer list, or returns 400. customerStatus isn’t checked: a customer the merchant excluded, or who opted out, still gets the points and the call returns 200. To skip those customers, read customerStatus first
- Adds points to customer’s available balance immediately
- Creates a point transaction record with status “APPROVED” (or “PENDING” if the earn rule requires manual approval)
- Logs the activity with the provided note
- Updates customer’s total credited points
- Syncs updated points to Shopify metafields
- Returns updated customer loyalty information
Important notes:
- Points are added to availablePoints immediately, unless the earn rule in earnRuleId requires manual approval (then they’re pending)
- Points do NOT expire unless you have expiration rules configured
- points must be greater than 0, or the request fails with 400. To deduct points, use the remove-points endpoint
- The transaction is recorded with transactionRule “ADJUSTMENT”, or “EARN_RULE” when you send earnRuleId
- Note field appears in customer’s transaction history
- earnRuleId is optional. When sent, it must match an active earn rule in your store that is within its scheduled dates, or the request fails with 400
Best practices:
- Always include a descriptive note explaining why points were added
- Use consistent note format for easier reporting
- Send earnRuleId only when the points belong to a specific earn rule; omit it for plain manual adjustments
- Verify customer ID/email before making API call
- Points are added in real-time - no undo functionality
Example notes:
- “Bonus points for email signup - January promotion”
- “Compensation for delayed shipping - Order #1234”
- “Referral bonus from external system”
- “Migration - transferred from old loyalty system”
- “Birthday bonus - 2025”
curl --request POST \
--url https://loyalty-admin.appstle.com/api/external/add-points \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <x-api-key>' \
--data '{
"points": 50
}'import requests
url = "https://loyalty-admin.appstle.com/api/external/add-points"
payload = { "points": 50 }
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({points: 50})
};
fetch('https://loyalty-admin.appstle.com/api/external/add-points', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://loyalty-admin.appstle.com/api/external/add-points';
const options = {
method: 'POST',
headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({points: 50})
};
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/add-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([
'points' => 50
]),
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/add-points"
payload := strings.NewReader("{\n \"points\": 50\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/add-points")
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 \"points\": 50\n}"
response = http.request(request)
puts response.read_body{
"availablePoints": 350,
"creditedPoints": 600,
"currentVipTier": "Gold",
"customerStatus": "ACTIVE",
"pendingPoints": 0,
"rewards": [],
"spentAmount": 1250.99,
"storeCreditBalance": 0
}{
"status": 400,
"title": "Points must be greater than 0"
}{
"detail": "Invalid authentication",
"status": 401
}Body
Request containing customer ID/email, points to add, and optional description
Number of points to add to the customer's account. Must be greater than 0. Points are added to availablePoints immediately, unless the earn rule in earnRuleId requires manual approval. Decimal values are supported for fractional points. Example: 50.0
x >= 0.0150
Customer's email address. Alternative to customerId for identifying the customer. Provide customerId or customerEmail. When you send both, customerId is used. Must be the email of a customer in your store's loyalty customer list, or the call returns 400 with the title "Customer not found using this email". Email matching is case-insensitive. Example: customer@example.com
"customer@example.com"
Shopify customer ID (numeric). Identifies the customer whose points change. Provide customerId or customerEmail. When you send both, customerId is used. The customer must be in your store's loyalty customer list, or the call returns 400 with the title "Customer not found using this customerID". The customer's status isn't checked: the call also works for a customer the merchant excluded or who opted out. Example: 67890
67890
Optional: ID of an earn rule to record this transaction under. The number of points always comes from the points field. When adding points, the earn rule must exist in your store, be active and be within its scheduled dates, otherwise the request fails with 400 ("Point Earn Rule not found" or "Point Earn Rule is not active"). If the earn rule requires manual approval, the added points are pending until approved. When removing points, the ID is only stored on the transaction. Example: 10
10
Optional but strongly recommended: Description of why points are being added. This note appears in the customer's transaction history and admin logs. Best practices:
- Be specific about the reason
- Include reference numbers (order ID, ticket ID, etc.)
- Use consistent formatting for easier reporting Examples:
- "Birthday bonus - January 2025"
- "Compensation for delayed shipping - Order #1234"
- "Referral bonus from external campaign"
- "Migration - transferred from old system"
- "Manual adjustment per support ticket #567"
500"Compensation for delayed shipping - Order #1234"
Response
Points successfully added to customer account
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://loyalty-admin.appstle.com/api/external/add-points \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <x-api-key>' \
--data '{
"points": 50
}'import requests
url = "https://loyalty-admin.appstle.com/api/external/add-points"
payload = { "points": 50 }
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({points: 50})
};
fetch('https://loyalty-admin.appstle.com/api/external/add-points', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://loyalty-admin.appstle.com/api/external/add-points';
const options = {
method: 'POST',
headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({points: 50})
};
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/add-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([
'points' => 50
]),
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/add-points"
payload := strings.NewReader("{\n \"points\": 50\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/add-points")
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 \"points\": 50\n}"
response = http.request(request)
puts response.read_body{
"availablePoints": 350,
"creditedPoints": 600,
"currentVipTier": "Gold",
"customerStatus": "ACTIVE",
"pendingPoints": 0,
"rewards": [],
"spentAmount": 1250.99,
"storeCreditBalance": 0
}{
"status": 400,
"title": "Points must be greater than 0"
}{
"detail": "Invalid authentication",
"status": 401
}