> 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.md).

# Classic REST API

The classic routes of the Shopwaive API, with no version in the path: every request, how to test it with your own key, and the errors

{% hint style="info" %}
Every request needs a Shopwaive API key in the `X-Shopwaive-Access-Token` header. To create one, see the [Quick Start](https://api.shopwaive.com/classic/quick-start.md#get-your-api-keys). Still on an old store access token? See [API keys and Shopify expiring tokens](https://api.shopwaive.com/classic/api-keys-and-shopify-expiring-tokens.md).
{% endhint %}

{% hint style="warning" %}
**These routes are deprecated.** The current release is the **Shopwaive API 2026-11**, with its version in every path (`/api/2026-11/...`): choose 2026-11 in the version menu, or open [its reference](https://api.shopwaive.com/api-2026-11/reference). [Move from the classic routes](https://api.shopwaive.com/guides/migrate-from-the-classic-routes) maps each request to its 2026-11 request.
{% endhint %}

## Requests

| API                                                                                                | Requests                                                                                                                                                                       |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Customer API](https://api.shopwaive.com/classic/reference/rest-api-documentation/customer-api.md) | `GET /api/customer/{customer_email}`, `POST /api/customer`, `PUT /api/customer`                                                                                                |
| [Action API](https://api.shopwaive.com/classic/reference/rest-api-documentation/action-api.md)     | `GET /api/actions`, `GET /api/action/{actionid}`, `POST /api/action/{actionid}`, `DELETE /api/action/{actionid}`                                                               |
| [Loyalty API](https://api.shopwaive.com/classic/reference/rest-api-documentation/loyalty-api.md)   | `GET /api/loyalty/program`, `GET /api/loyalty/tiers`, `GET /api/loyalty/members/{customer}`, `GET /api/loyalty/members/{customer}/activity`, `GET /api/loyalty/orders/{order}` |
| [Shopify Flow](https://api.shopwaive.com/classic/reference/rest-api-documentation/shopify-flow.md) | `POST /api/trigger`                                                                                                                                                            |

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

### Changes on 26 October 2026

* **Shopwaive API keys.** Every request takes a key from **Settings** > **Developers** > **Shopwaive API keys**, sent in `X-Shopwaive-Access-Token`.
* **Test it.** Every request on these pages has a **Test it** button that sends a real request with your own key.
* **Loyalty API** in the reference: five reads of the store's points program.
* **Shopify Flow** in the reference: `POST /api/trigger` starts your Shopify Flow workflows.
* **Retry safely.** Every request that changes something needs an `Idempotency-Key` header: `POST` and `PUT /api/customer`, `POST` and `DELETE /api/action/{actionid}`, and `POST /api/trigger`. Send a new value for each change and the same value on a retry: a retry with the same key changes nothing twice. Without the header, a request made with a Shopwaive API key returns HTTP `400` with the reason `idempotency_key_required`, and nothing is changed.
* **`DELETE /api/action/{actionid}`** needs your key in `X-Shopwaive-Access-Token`. When an entry shows a `remaining` amount above 0 and below its amount, only `remaining` is reversed.
* **`POST /api/action/{actionid}`** changes an entry's note, expiry or media. It answers HTTP `200` with the plain text `OK`.
* **`GET /api/customer/{customer_email}`** documents `isocode`, to read the balance in another currency.
* **Errors** are documented for every request, below and on each request's page, built from what the API answers today.
* **Request id.** Every answer carries an `X-Shopwaive-Request-Id` header (from 26 Oct 2026). Quote it when you contact support.

## Test it with your own key

1. Create a key: see the [Quick Start](https://api.shopwaive.com/classic/quick-start.md#get-your-api-keys).
2. On any request on these pages, press **Test it**.
3. Enter your key for `X-Shopwaive-Access-Token`. Keep `X-Shopwaive-Platform` as `shopify`. For a request that changes something, enter a new `Idempotency-Key`, for example a UUID.
4. Fill in the fields and send the request.

GitBook sends the request from its own servers to `https://app.shopwaive.com`, so it works in any browser. Your key goes through GitBook to Shopwaive.

{% hint style="warning" %}
A test is a real request. `POST`, `PUT` and `DELETE` change real balances and entries in your store, and `POST /api/trigger` starts your real workflows. Test with a customer you made for testing. You can revoke a key you used for tests in **Settings** > **Developers**.
{% endhint %}

## Errors

| Status         | Body                                                                                                             | When                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`          | `{"error": "unknown_api_token", "message": "..."}`                                                               | No key, or a token Shopwaive does not know.                                                                                                                                                                                                                                                                                                                                                                                 |
| `401`          | `{"status": "failed", "message": "Invalid X-Shopwaive-Access-Token: key-revoked."}`                              | A `swak_` key was not accepted. The message names the reason: see [If a key is not accepted](https://api.shopwaive.com/classic/quick-start.md#if-a-key-is-not-accepted).                                                                                                                                                                                                                                                    |
| `400`          | `{"status": "failed", "reason": "idempotency_key_required", ...}`                                                | A request that changes something was sent with a key and without an `Idempotency-Key` header. Nothing was changed. See [Retry safely](https://api.shopwaive.com/classic/reference/rest-api-documentation/customer-api.md#retry-safely).                                                                                                                                                                                     |
| `200` or `201` | `status` "Shopwaive API currently only supports stores on Shopify. Invalid X-Shopwaive-Platform header."         | `X-Shopwaive-Platform` is missing or is not `shopify`. `GET /api/customer` answers `200` (with `"status": "failed"`), the other Customer and Action API requests `201`. Nothing is changed. `POST /api/trigger` and the Loyalty API do not need this header.                                                                                                                                                                |
| `405`          | The plain text `Method Not Allowed`                                                                              | The email address is not valid, or the path does not take the request's method (the `Allow` header lists the methods it takes), and nothing was changed. On `POST` or `PUT /api/customer` with a valid address or a `segment_query`, it means Shopwaive sent the change, but could not read its result. The change may have been made, a deposit to a customer segment included. Read the balance before you send it again. |
| `405`          | `{"status": "failed_store_limit", "message": "..."}` or `{"status": "failed_balance_service", "message": "..."}` | `PUT /api/customer`: the deposit was not made. Nothing was changed. Contact <support@shopwaive.com> with the request id.                                                                                                                                                                                                                                                                                                    |
| `429`          | `{"error": "Too many requests. ..."}`                                                                            | Too many requests. Wait the seconds in `Retry-After`. See [rate limits](https://api.shopwaive.com/classic/reference/shopwaive-api-rate-limits.md).                                                                                                                                                                                                                                                                          |
| `503`          | `{"status": "failed_temporary", "message": "..."}`                                                               | The key could not be checked just now. Nothing was changed. Retry after `Retry-After` (30 seconds).                                                                                                                                                                                                                                                                                                                         |
| `503`          | `{"status": "failed", "message": "Shopwaive API key lookup is temporarily unavailable. Retry."}`                 | A `swak_` key could not be checked just now. Retry.                                                                                                                                                                                                                                                                                                                                                                         |

Every answer carries an `X-Shopwaive-Request-Id` header. When you write to <support@shopwaive.com> about a request, include it.

The [Loyalty API](https://api.shopwaive.com/classic/reference/rest-api-documentation/loyalty-api.md#answers-and-errors) has its own error bodies. Retries with an `Idempotency-Key` have their own answers: see [Retry safely](https://api.shopwaive.com/classic/reference/rest-api-documentation/customer-api.md#retry-safely).

## Earlier releases

* **November 2024:** `GET /api/actions` searches entries by `email`, `created_at_min` and `created_at_max`.
* **May 2024:** `GET /api/customer/{customer_email}` returns `activity`, `orders` and `offers` only when you ask with `activity=true`, `orders=true` or `offers=true`. The `transaction` field of an entry is deprecated: do not rely on it. `expirationdate` and `expires` can be sent to `POST` and `PUT /api/customer`.
