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

# Loyalty for developers

Read a store's loyalty program, members and orders over the Shopwaive REST API

## Shopwaive API keys and scopes <a href="#shopwaive-api-keys-and-scopes" id="shopwaive-api-keys-and-scopes"></a>

Create a key under **Settings** > **Developers** > **Shopwaive API keys** in Shopwaive, and choose what it may do when you make it. A key belongs to one store and works only for that store. It can call a loyalty route only when it holds the route's scope, and a key made before scopes existed holds none.

| Scope          | What it allows                                           |
| -------------- | -------------------------------------------------------- |
| `members:read` | Read members and their points.                           |
| `reports:read` | Read loyalty reports, such as the program and its tiers. |

Send the key in the `X-Shopwaive-Access-Token` header, as for every Shopwaive API request. The loyalty routes also take it in the `X-Shopwaive-Api-Key` header, or as `Authorization: Bearer` followed by the key. The same reads are on [api.shopwaive.com](https://api.shopwaive.com/reference/rest-api-documentation/loyalty-api).

## REST API: loyalty reads <a href="#rest-api-loyalty-reads" id="rest-api-loyalty-reads"></a>

The reads are at `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. Each key can make 20 read requests a second, with short bursts up to 40. A request over the limit is answered with the time to wait before the next one.

## Points and Shopify Flow <a href="#points-and-shopify-flow" id="points-and-shopify-flow"></a>

Your loyalty program pays points on orders by itself, with no workflow. To deposit to a balance from Shopify Flow, use the **Increment balance** action: see [Shopify Flow](https://docs.shopwaive.com/shopify/shopify-flow.md). Its deposits are not part of your loyalty program, so Shopwaive does not take them back on a refund.
