Loyalty API
Read a store's loyalty program, its tiers, a member's points and history, and each order's points with the Shopwaive Loyalty API (2026-11). Read only
The Loyalty API reads the points program a store runs on the Loyalty page of the Shopwaive app. It is read only. Merchants set up and launch the program in the app: see Loyalty in the Help Center.
Authentication
Send a Shopwaive API key in the X-Shopwaive-Access-Token header, as for every Shopwaive API request. The loyalty routes also take the key in the X-Shopwaive-Api-Key header, or as Authorization: Bearer followed by the key. To create a key, see the Quick Start.
A key can call a loyalty route only when it holds the route's scope. Choose the scopes when you create the key, under What the new key can do. A key made before scopes existed holds none: create a new key for loyalty reads. A key belongs to one store and reads only that store.
members:read
Read members, their points and their history, and each order's points.
reports:read
Read the program and its tiers.
points:write, activities:write, members:write, events:manage
You can choose them in the app, but no request on this page uses them.
Endpoints
Base URL: https://app.shopwaive.com
GET /api/loyalty/program
The program Shopwaive runs at the store.
members:read or reports:read
GET /api/loyalty/tiers
The tier table of the program version Shopwaive runs.
members:read or reports:read
GET /api/loyalty/members/{customer}
One member: their standing and their balance.
members:read
GET /api/loyalty/members/{customer}/activity
The member's balance history, newest first.
members:read
GET /api/loyalty/orders/{order}
One order's loyalty record: the points it added, and any points taken back.
members:read
{customer} and {order} are Shopify ids: the number, or the full id URL encoded, for example gid%3A%2F%2Fshopify%2FCustomer%2F1234567890.
The activity route takes two optional query parameters: limit, from 1 to 100 (25 if you leave it out), and before. To read the next page, send the next_before value of the page you have as before.
Try each request
Press Test it on a request and enter your own key. See Test it with your own key.
GET program
The program Shopwaive runs at the store.
Returns the program Shopwaive runs at the store, and how the store shows a balance. Needs a key with the scope members:read or reports:read.
Your Shopwaive API key. Create it in the Shopwaive app under Settings > Develop > Shopwaive API keys. It starts with swak_.
The program. program is null when the store has none.
No key, not a Shopwaive API key, a key not recognised, a revoked key, or a store that uninstalled Shopwaive. reason names which. A key of a store that uninstalled Shopwaive (app_uninstalled) is paused, not revoked; it works again when the app is reinstalled.
The key does not hold the route's scope.
More than 20 requests a second with this key (short bursts up to 40 are allowed). Wait the seconds in Retry-After.
Try again later. When a Retry-After header is sent, wait that many seconds.
GET /api/loyalty/program HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: swak_YOUR_API_KEY
Accept: */*
{
"v": 1,
"mode": "none",
"program": {
"version": 1,
"saved_at": null,
"sha256": null,
"rules": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"problem": null,
"display": {
"currency": null,
"symbol": null,
"shown_as": "points",
"points_multiplier": null
}
}GET tiers
The tier table of the program version Shopwaive runs.
Returns the tier table of the program version Shopwaive runs. Needs a key with the scope members:read or reports:read.
Your Shopwaive API key. Create it in the Shopwaive app under Settings > Develop > Shopwaive API keys. It starts with swak_.
The tiers. tiers is null when the program has no tier table.
No key, not a Shopwaive API key, a key not recognised, a revoked key, or a store that uninstalled Shopwaive. reason names which. A key of a store that uninstalled Shopwaive (app_uninstalled) is paused, not revoked; it works again when the app is reinstalled.
The key does not hold the route's scope.
More than 20 requests a second with this key (short bursts up to 40 are allowed). Wait the seconds in Retry-After.
Try again later. When a Retry-After header is sent, wait that many seconds.
GET /api/loyalty/tiers HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: swak_YOUR_API_KEY
Accept: */*
{
"v": 1,
"mode": "none",
"version": null,
"tiers": {
"on": true,
"list": [
{
"key": null,
"label": null,
"at": null,
"rate": null
}
]
}
}GET member
One member: their standing and their balance.
Returns one member's standing and balance. Needs a key with the scope members:read.
Your Shopwaive API key. Create it in the Shopwaive app under Settings > Develop > Shopwaive API keys. It starts with swak_.
The Shopify customer id. The number, or the full id URL encoded, for example gid%3A%2F%2Fshopify%2FCustomer%2F1234567890.
1234567890The member.
An id or a query parameter is not valid.
No key, not a Shopwaive API key, a key not recognised, a revoked key, or a store that uninstalled Shopwaive. reason names which. A key of a store that uninstalled Shopwaive (app_uninstalled) is paused, not revoked; it works again when the app is reinstalled.
The key does not hold the route's scope.
The store has no loyalty record for that customer or order.
More than 20 requests a second with this key (short bursts up to 40 are allowed). Wait the seconds in Retry-After.
Try again later. When a Retry-After header is sent, wait that many seconds.
GET /api/loyalty/members/{customer} HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: swak_YOUR_API_KEY
Accept: */*
{
"v": 1,
"customer_id": "text",
"mode": "none",
"member": {
"first_seen_at": null,
"last_seen_at": null,
"orders": null,
"tier": {
"key": "text",
"name": null
}
},
"balance": {
"credit": "text",
"unit": "points",
"currency": null,
"scale": null
},
"balance_note": null,
"wallets_with_stamp": 1
}GET member activity
The member's balance history, newest first.
Returns the member's balance history, newest first. Needs a key with the scope members:read.
To read the next page, send the next_before value of the page you have as before.
Your Shopwaive API key. Create it in the Shopwaive app under Settings > Develop > Shopwaive API keys. It starts with swak_.
The Shopify customer id. The number, or the full id URL encoded, for example gid%3A%2F%2Fshopify%2FCustomer%2F1234567890.
1234567890How many lines, from 1 to 100. 25 if you leave it out.
25Only lines older than this one. Use the next_before value of the previous page.
One page of the history.
An id or a query parameter is not valid.
No key, not a Shopwaive API key, a key not recognised, a revoked key, or a store that uninstalled Shopwaive. reason names which. A key of a store that uninstalled Shopwaive (app_uninstalled) is paused, not revoked; it works again when the app is reinstalled.
The key does not hold the route's scope.
The store has no loyalty record for that customer or order.
More than 20 requests a second with this key (short bursts up to 40 are allowed). Wait the seconds in Retry-After.
Try again later. When a Retry-After header is sent, wait that many seconds.
GET /api/loyalty/members/{customer}/activity HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: swak_YOUR_API_KEY
Accept: */*
{
"v": 1,
"customer_id": "text",
"lines": [
{
"seq": 1,
"at": null,
"kind": null,
"amount": null,
"balance_after": null,
"by": "loyalty_engine",
"engine_kind": null,
"order_id": null,
"note": null
}
],
"next_before": null,
"older_entries_not_listed": 1,
"unit": null,
"currency": null,
"note": null
}GET order
One order's loyalty record.
Returns one order's loyalty record. It shows the points the order added, the points due and not added, and any points taken back. Needs a key with the scope members:read.
Your Shopwaive API key. Create it in the Shopwaive app under Settings > Develop > Shopwaive API keys. It starts with swak_.
The Shopify order id. The number, or the full id URL encoded, for example gid%3A%2F%2Fshopify%2FOrder%2F1234567890.
1234567890The order's loyalty record.
An id or a query parameter is not valid.
No key, not a Shopwaive API key, a key not recognised, a revoked key, or a store that uninstalled Shopwaive. reason names which. A key of a store that uninstalled Shopwaive (app_uninstalled) is paused, not revoked; it works again when the app is reinstalled.
The key does not hold the route's scope.
The store has no loyalty record for that customer or order.
More than 20 requests a second with this key (short bursts up to 40 are allowed). Wait the seconds in Retry-After.
Try again later. When a Retry-After header is sent, wait that many seconds.
GET /api/loyalty/orders/{order} HTTP/1.1
Host: app.shopwaive.com
X-Shopwaive-Access-Token: swak_YOUR_API_KEY
Accept: */*
{
"v": 1,
"order_id": "text",
"customer_id": null,
"state": "added",
"points": {
"will_add": null,
"added": null,
"taken_back": null
},
"added_by": "engine",
"earning": null,
"take_back": null,
"moment": null,
"reason": null,
"placed_at": null,
"program_version": null,
"mode": "none"
}Example
swak_EXAMPLEKEY000000000000000000000000000000 is an example, not a real key. Use your own key, and keep it on your server.
Answers and errors
Every answer is JSON and carries the X-Shopwaive-Api-Version and X-Shopwaive-Request-Id headers. X-Shopwaive-Api-Version names the version of the loyalty routes, 2026-10 today; requests do not choose a version.
200
The record you asked for.
The request worked.
400
{"error": "customer_id_invalid"}, or order_id_invalid, limit_invalid, before_invalid
An id or a query parameter is not valid.
401
{"error": "unauthorized", "reason": "key-revoked"}
No key, not a Shopwaive API key, a key not recognised, a revoked key, or a store that uninstalled. The reason names which: a key of a store that uninstalled has app_uninstalled, and it is paused, not revoked: it works again when the app is reinstalled.
403
{"error": "missing_scope", "scope": "members:read"}
The key does not hold the route's scope.
404
{"error": "member_not_found"} or {"error": "order_not_found"}
The store has no loyalty record for that customer or order.
429
{"error": "rate_limited"}
Too many requests. The Retry-After header gives the seconds to wait.
503
{"error": "temporarily_unavailable"}
Try again later.
Rate limits
Each key can make 20 requests a second, with short bursts up to 40. A request over the limit returns 429 with a Retry-After header.
Last updated