> For the complete documentation index, see [llms.txt](https://api.shopwaive.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.shopwaive.com/classic/reference/rest-api-documentation/loyalty-api.md).

# 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. 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](https://docs.shopwaive.com/shopify/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](https://api.shopwaive.com/classic/quick-start.md#get-your-api-keys).

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.

| Scope          | What it allows                                                         |
| -------------- | ---------------------------------------------------------------------- |
| `members:read` | Read members, their points and their history, and each order's points. |
| `reports:read` | Read the program and its tiers.                                        |

## Endpoints

Base URL: `https://app.shopwaive.com`

| Request                                        | What it returns                                                             | Scope                            |
| ---------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------- |
| `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](https://api.shopwaive.com/classic/reference/rest-api-documentation.md#test-it-with-your-own-key).

### `GET` program

The program Shopwaive runs at the store.

## Get the loyalty program

> 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\`.

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Loyalty API","description":"Read the store's loyalty program, its tiers, a member's points and history, and each order's points. Read only."}],"servers":[{"url":"https://app.shopwaive.com","description":"Shopwaive API"}],"security":[{"ShopwaiveApiKey":[]}],"components":{"securitySchemes":{"ShopwaiveApiKey":{"type":"apiKey","in":"header","name":"X-Shopwaive-Access-Token","description":"Your Shopwaive API key. Create it in the Shopwaive app under Settings > Developers > Shopwaive API keys. It starts with swak_."}},"headers":{"RequestId":{"description":"This answer's request id, 16 hexadecimal characters. Every answer carries it. Quote it when you contact support.","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"}},"LoyaltyApiVersion":{"description":"The version of the loyalty routes that answered.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before you retry.","schema":{"type":"integer"}}},"schemas":{"LoyaltyProgram":{"type":"object","properties":{"v":{"type":"integer","const":1},"mode":{"$ref":"#/components/schemas/LoyaltyMode"},"program":{"description":"The program version Shopwaive runs, or null.","type":["object","null"],"properties":{"version":{"type":"integer"},"saved_at":{"type":["string","null"]},"sha256":{"type":["string","null"]},"rules":{"description":"The program's settings, as saved on the Loyalty page.","type":"object","additionalProperties":true}}},"problem":{"description":"Why the program could not be read, or null.","type":["string","null"]},"display":{"description":"How the store shows a balance.","type":"object","properties":{"currency":{"type":["string","null"]},"symbol":{"type":["string","null"]},"shown_as":{"type":"string","enum":["points","money"]},"points_multiplier":{"description":"The points shown for each unit of a stored balance. null when it cannot be read.","type":["number","null"]}}}}},"LoyaltyMode":{"description":"The state the loyalty engine serves the store in: `live`, `test` (only the store's test customers), `drain` (paused: points owed are added when the program is Live again), `off`, or `none` (no program). `preview` and `earn` are other engine states. Points are paid in `test`, `earn` and `live`.","type":"string","enum":["none","off","preview","test","earn","live","drain"]},"LoyaltyError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["customer_id_invalid","order_id_invalid","limit_invalid","before_invalid","unauthorized","missing_scope","member_not_found","order_not_found","rate_limited","temporarily_unavailable","not_configured"]},"reason":{"description":"With `unauthorized`.","type":"string","enum":["no-key-presented","not-a-shopwaive-api-key","key-not-recognised","key-revoked","app_uninstalled"]},"scope":{"description":"With `missing_scope`. The scope the route needs.","type":"string"}}}},"responses":{"LoyaltyUnauthorized":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyMissingScope":{"description":"The key does not hold the route's scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyRateLimited":{"description":"More than 20 requests a second with this key (short bursts up to 40 are allowed). Wait the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyUnavailable":{"description":"Try again later. When a Retry-After header is sent, wait that many seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}}}},"paths":{"/api/loyalty/program":{"get":{"tags":["Loyalty API"],"operationId":"getLoyaltyProgram","summary":"Get the loyalty program","description":"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`.","responses":{"200":{"description":"The program. `program` is null when the store has none.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Shopwaive-Api-Version":{"$ref":"#/components/headers/LoyaltyApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyProgram"}}}},"401":{"$ref":"#/components/responses/LoyaltyUnauthorized"},"403":{"$ref":"#/components/responses/LoyaltyMissingScope"},"429":{"$ref":"#/components/responses/LoyaltyRateLimited"},"503":{"$ref":"#/components/responses/LoyaltyUnavailable"}}}}}}
```

### `GET` tiers

The tier table of the program version Shopwaive runs.

## Get the program's tiers

> Returns the tier table of the program version Shopwaive runs. Needs a key with the scope \`members:read\` or \`reports:read\`.

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Loyalty API","description":"Read the store's loyalty program, its tiers, a member's points and history, and each order's points. Read only."}],"servers":[{"url":"https://app.shopwaive.com","description":"Shopwaive API"}],"security":[{"ShopwaiveApiKey":[]}],"components":{"securitySchemes":{"ShopwaiveApiKey":{"type":"apiKey","in":"header","name":"X-Shopwaive-Access-Token","description":"Your Shopwaive API key. Create it in the Shopwaive app under Settings > Developers > Shopwaive API keys. It starts with swak_."}},"headers":{"RequestId":{"description":"This answer's request id, 16 hexadecimal characters. Every answer carries it. Quote it when you contact support.","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"}},"LoyaltyApiVersion":{"description":"The version of the loyalty routes that answered.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before you retry.","schema":{"type":"integer"}}},"schemas":{"LoyaltyTiers":{"type":"object","properties":{"v":{"type":"integer","const":1},"mode":{"$ref":"#/components/schemas/LoyaltyMode"},"version":{"description":"The program version the tiers belong to, or null.","type":["integer","null"]},"tiers":{"type":["object","null"],"properties":{"on":{"description":"Whether tiers are switched on.","type":"boolean"},"list":{"type":"array","items":{"type":"object","properties":{"key":{"type":["string","null"]},"label":{"type":["string","null"]},"at":{"description":"What a member needs to reach the tier, as saved in the program."},"rate":{"description":"The tier's earn rate, as saved in the program."}}}}}}}},"LoyaltyMode":{"description":"The state the loyalty engine serves the store in: `live`, `test` (only the store's test customers), `drain` (paused: points owed are added when the program is Live again), `off`, or `none` (no program). `preview` and `earn` are other engine states. Points are paid in `test`, `earn` and `live`.","type":"string","enum":["none","off","preview","test","earn","live","drain"]},"LoyaltyError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["customer_id_invalid","order_id_invalid","limit_invalid","before_invalid","unauthorized","missing_scope","member_not_found","order_not_found","rate_limited","temporarily_unavailable","not_configured"]},"reason":{"description":"With `unauthorized`.","type":"string","enum":["no-key-presented","not-a-shopwaive-api-key","key-not-recognised","key-revoked","app_uninstalled"]},"scope":{"description":"With `missing_scope`. The scope the route needs.","type":"string"}}}},"responses":{"LoyaltyUnauthorized":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyMissingScope":{"description":"The key does not hold the route's scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyRateLimited":{"description":"More than 20 requests a second with this key (short bursts up to 40 are allowed). Wait the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyUnavailable":{"description":"Try again later. When a Retry-After header is sent, wait that many seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}}}},"paths":{"/api/loyalty/tiers":{"get":{"tags":["Loyalty API"],"operationId":"getLoyaltyTiers","summary":"Get the program's tiers","description":"Returns the tier table of the program version Shopwaive runs. Needs a key with the scope `members:read` or `reports:read`.","responses":{"200":{"description":"The tiers. `tiers` is null when the program has no tier table.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Shopwaive-Api-Version":{"$ref":"#/components/headers/LoyaltyApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyTiers"}}}},"401":{"$ref":"#/components/responses/LoyaltyUnauthorized"},"403":{"$ref":"#/components/responses/LoyaltyMissingScope"},"429":{"$ref":"#/components/responses/LoyaltyRateLimited"},"503":{"$ref":"#/components/responses/LoyaltyUnavailable"}}}}}}
```

### `GET` member

One member: their standing and their balance.

## Get a member

> Returns one member's standing and balance. Needs a key with the scope \`members:read\`.

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Loyalty API","description":"Read the store's loyalty program, its tiers, a member's points and history, and each order's points. Read only."}],"servers":[{"url":"https://app.shopwaive.com","description":"Shopwaive API"}],"security":[{"ShopwaiveApiKey":[]}],"components":{"securitySchemes":{"ShopwaiveApiKey":{"type":"apiKey","in":"header","name":"X-Shopwaive-Access-Token","description":"Your Shopwaive API key. Create it in the Shopwaive app under Settings > Developers > Shopwaive API keys. It starts with swak_."}},"parameters":{"LoyaltyCustomer":{"name":"customer","in":"path","required":true,"description":"The Shopify customer id. The number, or the full id URL encoded, for example `gid%3A%2F%2Fshopify%2FCustomer%2F1234567890`.","schema":{"type":"string"}}},"headers":{"RequestId":{"description":"This answer's request id, 16 hexadecimal characters. Every answer carries it. Quote it when you contact support.","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"}},"LoyaltyApiVersion":{"description":"The version of the loyalty routes that answered.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before you retry.","schema":{"type":"integer"}}},"schemas":{"LoyaltyMember":{"type":"object","properties":{"v":{"type":"integer","const":1},"customer_id":{"type":"string"},"mode":{"$ref":"#/components/schemas/LoyaltyMode"},"member":{"description":"The member's loyalty record, or null when the program has none for this customer yet.","type":["object","null"],"properties":{"first_seen_at":{"type":["string","null"]},"last_seen_at":{"type":["string","null"]},"orders":{"type":["integer","null"]},"tier":{"type":["object","null"],"properties":{"key":{"type":"string"},"name":{"type":["string","null"]}}}}},"balance":{"$ref":"#/components/schemas/LoyaltyBalance"},"balance_note":{"description":"Why `balance` is null, or null.","type":["string","null"]}}},"LoyaltyMode":{"description":"The state the loyalty engine serves the store in: `live`, `test` (only the store's test customers), `drain` (paused: points owed are added when the program is Live again), `off`, or `none` (no program). `preview` and `earn` are other engine states. Points are paid in `test`, `earn` and `live`.","type":"string","enum":["none","off","preview","test","earn","live","drain"]},"LoyaltyBalance":{"description":"The member's balance from their wallet, in the wallet's own units. null when Shopwaive cannot read it (see `balance_note`).","type":["object","null"],"properties":{"credit":{"description":"The balance as exact decimal text.","type":"string"},"unit":{"type":["string","null"],"enum":["points","money",null]},"currency":{"type":["string","null"]},"scale":{"description":"Minor units in one unit of the balance.","type":["integer","null"]}}},"LoyaltyError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["customer_id_invalid","order_id_invalid","limit_invalid","before_invalid","unauthorized","missing_scope","member_not_found","order_not_found","rate_limited","temporarily_unavailable","not_configured"]},"reason":{"description":"With `unauthorized`.","type":"string","enum":["no-key-presented","not-a-shopwaive-api-key","key-not-recognised","key-revoked","app_uninstalled"]},"scope":{"description":"With `missing_scope`. The scope the route needs.","type":"string"}}}},"responses":{"LoyaltyBadRequest":{"description":"An id or a query parameter is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyUnauthorized":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyMissingScope":{"description":"The key does not hold the route's scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyNotFound":{"description":"The store has no loyalty record for that customer or order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyRateLimited":{"description":"More than 20 requests a second with this key (short bursts up to 40 are allowed). Wait the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyUnavailable":{"description":"Try again later. When a Retry-After header is sent, wait that many seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}}}},"paths":{"/api/loyalty/members/{customer}":{"get":{"tags":["Loyalty API"],"operationId":"getLoyaltyMember","summary":"Get a member","description":"Returns one member's standing and balance. Needs a key with the scope `members:read`.","parameters":[{"$ref":"#/components/parameters/LoyaltyCustomer"}],"responses":{"200":{"description":"The member.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Shopwaive-Api-Version":{"$ref":"#/components/headers/LoyaltyApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyMember"}}}},"400":{"$ref":"#/components/responses/LoyaltyBadRequest"},"401":{"$ref":"#/components/responses/LoyaltyUnauthorized"},"403":{"$ref":"#/components/responses/LoyaltyMissingScope"},"404":{"$ref":"#/components/responses/LoyaltyNotFound"},"429":{"$ref":"#/components/responses/LoyaltyRateLimited"},"503":{"$ref":"#/components/responses/LoyaltyUnavailable"}}}}}}
```

### `GET` member activity

The member's balance history, newest first.

## Get a member's balance history

> 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\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Loyalty API","description":"Read the store's loyalty program, its tiers, a member's points and history, and each order's points. Read only."}],"servers":[{"url":"https://app.shopwaive.com","description":"Shopwaive API"}],"security":[{"ShopwaiveApiKey":[]}],"components":{"securitySchemes":{"ShopwaiveApiKey":{"type":"apiKey","in":"header","name":"X-Shopwaive-Access-Token","description":"Your Shopwaive API key. Create it in the Shopwaive app under Settings > Developers > Shopwaive API keys. It starts with swak_."}},"parameters":{"LoyaltyCustomer":{"name":"customer","in":"path","required":true,"description":"The Shopify customer id. The number, or the full id URL encoded, for example `gid%3A%2F%2Fshopify%2FCustomer%2F1234567890`.","schema":{"type":"string"}}},"headers":{"RequestId":{"description":"This answer's request id, 16 hexadecimal characters. Every answer carries it. Quote it when you contact support.","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"}},"LoyaltyApiVersion":{"description":"The version of the loyalty routes that answered.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before you retry.","schema":{"type":"integer"}}},"schemas":{"LoyaltyActivity":{"type":"object","properties":{"v":{"type":"integer","const":1},"customer_id":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"seq":{"description":"The line's number in the wallet. Use it with `before`.","type":"integer"},"at":{"type":["string","null"]},"kind":{"type":["string","null"]},"amount":{"description":"The change, as exact decimal text.","type":["string","null"]},"balance_after":{"type":["string","null"]},"by":{"description":"`loyalty_engine`: the store's loyalty program; `other`: another change.","type":"string","enum":["loyalty_engine","other"]},"order_id":{"type":["string","null"]},"note":{"type":["string","null"]}}}},"next_before":{"description":"Send this as `before` to read the next page. null on the last page.","type":["integer","null"]},"older_entries_not_listed":{"description":"Older entries that predate the ledger figures, counted but not listed.","type":"integer"},"unit":{"type":["string","null"]},"currency":{"type":["string","null"]},"note":{"type":["string","null"]}}},"LoyaltyError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["customer_id_invalid","order_id_invalid","limit_invalid","before_invalid","unauthorized","missing_scope","member_not_found","order_not_found","rate_limited","temporarily_unavailable","not_configured"]},"reason":{"description":"With `unauthorized`.","type":"string","enum":["no-key-presented","not-a-shopwaive-api-key","key-not-recognised","key-revoked","app_uninstalled"]},"scope":{"description":"With `missing_scope`. The scope the route needs.","type":"string"}}}},"responses":{"LoyaltyBadRequest":{"description":"An id or a query parameter is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyUnauthorized":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyMissingScope":{"description":"The key does not hold the route's scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyNotFound":{"description":"The store has no loyalty record for that customer or order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyRateLimited":{"description":"More than 20 requests a second with this key (short bursts up to 40 are allowed). Wait the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyUnavailable":{"description":"Try again later. When a Retry-After header is sent, wait that many seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}}}},"paths":{"/api/loyalty/members/{customer}/activity":{"get":{"tags":["Loyalty API"],"operationId":"getLoyaltyMemberActivity","summary":"Get a member's balance history","description":"Returns the member's balance history, newest first. Needs a key with the scope `members:read`.\n\nTo read the next page, send the `next_before` value of the page you have as `before`.\n","parameters":[{"$ref":"#/components/parameters/LoyaltyCustomer"},{"name":"limit","in":"query","required":false,"description":"How many lines, from 1 to 100. 25 if you leave it out.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"before","in":"query","required":false,"description":"Only lines older than this one. Use the `next_before` value of the previous page.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"One page of the history.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Shopwaive-Api-Version":{"$ref":"#/components/headers/LoyaltyApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyActivity"}}}},"400":{"$ref":"#/components/responses/LoyaltyBadRequest"},"401":{"$ref":"#/components/responses/LoyaltyUnauthorized"},"403":{"$ref":"#/components/responses/LoyaltyMissingScope"},"404":{"$ref":"#/components/responses/LoyaltyNotFound"},"429":{"$ref":"#/components/responses/LoyaltyRateLimited"},"503":{"$ref":"#/components/responses/LoyaltyUnavailable"}}}}}}
```

### `GET` order

One order's loyalty record.

## Get an order's points

> 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\`.

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Loyalty API","description":"Read the store's loyalty program, its tiers, a member's points and history, and each order's points. Read only."}],"servers":[{"url":"https://app.shopwaive.com","description":"Shopwaive API"}],"security":[{"ShopwaiveApiKey":[]}],"components":{"securitySchemes":{"ShopwaiveApiKey":{"type":"apiKey","in":"header","name":"X-Shopwaive-Access-Token","description":"Your Shopwaive API key. Create it in the Shopwaive app under Settings > Developers > Shopwaive API keys. It starts with swak_."}},"headers":{"RequestId":{"description":"This answer's request id, 16 hexadecimal characters. Every answer carries it. Quote it when you contact support.","schema":{"type":"string","pattern":"^[0-9a-f]{16}$"}},"LoyaltyApiVersion":{"description":"The version of the loyalty routes that answered.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before you retry.","schema":{"type":"integer"}}},"schemas":{"LoyaltyOrder":{"type":"object","properties":{"v":{"type":"integer","const":1},"order_id":{"type":"string"},"customer_id":{"type":["string","null"]},"state":{"description":"`added` (points added), `waiting` (points due and not added), `reversed` (taken back or dropped), or `no_points`.","type":"string","enum":["added","waiting","reversed","no_points"]},"points":{"type":"object","properties":{"will_add":{"type":["string","null"]},"added":{"type":["string","null"]},"taken_back":{"type":["string","null"]}}},"added_by":{"description":"`engine`: the store's loyalty program; `other`: another change.","type":["string","null"],"enum":["engine","other",null]},"reason":{"type":["string","null"]},"placed_at":{"type":["string","null"]},"program_version":{"type":["integer","null"]},"mode":{"$ref":"#/components/schemas/LoyaltyMode"}}},"LoyaltyMode":{"description":"The state the loyalty engine serves the store in: `live`, `test` (only the store's test customers), `drain` (paused: points owed are added when the program is Live again), `off`, or `none` (no program). `preview` and `earn` are other engine states. Points are paid in `test`, `earn` and `live`.","type":"string","enum":["none","off","preview","test","earn","live","drain"]},"LoyaltyError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["customer_id_invalid","order_id_invalid","limit_invalid","before_invalid","unauthorized","missing_scope","member_not_found","order_not_found","rate_limited","temporarily_unavailable","not_configured"]},"reason":{"description":"With `unauthorized`.","type":"string","enum":["no-key-presented","not-a-shopwaive-api-key","key-not-recognised","key-revoked","app_uninstalled"]},"scope":{"description":"With `missing_scope`. The scope the route needs.","type":"string"}}}},"responses":{"LoyaltyBadRequest":{"description":"An id or a query parameter is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyUnauthorized":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyMissingScope":{"description":"The key does not hold the route's scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyNotFound":{"description":"The store has no loyalty record for that customer or order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyRateLimited":{"description":"More than 20 requests a second with this key (short bursts up to 40 are allowed). Wait the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}},"LoyaltyUnavailable":{"description":"Try again later. When a Retry-After header is sent, wait that many seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyError"}}}}}},"paths":{"/api/loyalty/orders/{order}":{"get":{"tags":["Loyalty API"],"operationId":"getLoyaltyOrder","summary":"Get an order's points","description":"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`.","parameters":[{"name":"order","in":"path","required":true,"description":"The Shopify order id. The number, or the full id URL encoded, for example `gid%3A%2F%2Fshopify%2FOrder%2F1234567890`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The order's loyalty record.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Shopwaive-Api-Version":{"$ref":"#/components/headers/LoyaltyApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyOrder"}}}},"400":{"$ref":"#/components/responses/LoyaltyBadRequest"},"401":{"$ref":"#/components/responses/LoyaltyUnauthorized"},"403":{"$ref":"#/components/responses/LoyaltyMissingScope"},"404":{"$ref":"#/components/responses/LoyaltyNotFound"},"429":{"$ref":"#/components/responses/LoyaltyRateLimited"},"503":{"$ref":"#/components/responses/LoyaltyUnavailable"}}}}}}
```

## Example

```bash
curl --location 'https://app.shopwaive.com/api/loyalty/members/1234567890' \
--header 'X-Shopwaive-Access-Token: swak_EXAMPLEKEY000000000000000000000000000000'
```

`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.

| Status | Body                                                                                         | When                                                                                                                                                                                                                                                           |
| ------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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.
