Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.

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

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.

GET program

The program Shopwaive runs at the store.

Get the loyalty program

get

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.

Authorizations
X-Shopwaive-Access-TokenstringRequired

Your Shopwaive API key. Create it in the Shopwaive app under Settings > Develop > Shopwaive API keys. It starts with swak_.

Responses
200

The program. program is null when the store has none.

application/json
get/api/loyalty/program
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.

Get the program's tiers

get

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

Authorizations
X-Shopwaive-Access-TokenstringRequired

Your Shopwaive API key. Create it in the Shopwaive app under Settings > Develop > Shopwaive API keys. It starts with swak_.

Responses
200

The tiers. tiers is null when the program has no tier table.

application/json
get/api/loyalty/tiers
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.

Get a member

get

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

Authorizations
X-Shopwaive-Access-TokenstringRequired

Your Shopwaive API key. Create it in the Shopwaive app under Settings > Develop > Shopwaive API keys. It starts with swak_.

Path parameters
customerstringRequired

The Shopify customer id. The number, or the full id URL encoded, for example gid%3A%2F%2Fshopify%2FCustomer%2F1234567890.

Example: 1234567890
Responses
200

The member.

application/json
get/api/loyalty/members/{customer}
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.

Get a member's balance history

get

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.

Authorizations
X-Shopwaive-Access-TokenstringRequired

Your Shopwaive API key. Create it in the Shopwaive app under Settings > Develop > Shopwaive API keys. It starts with swak_.

Path parameters
customerstringRequired

The Shopify customer id. The number, or the full id URL encoded, for example gid%3A%2F%2Fshopify%2FCustomer%2F1234567890.

Example: 1234567890
Query parameters
limitinteger · min: 1 · max: 100Optional

How many lines, from 1 to 100. 25 if you leave it out.

Default: 25
beforeinteger · min: 1Optional

Only lines older than this one. Use the next_before value of the previous page.

Responses
200

One page of the history.

application/json
get/api/loyalty/members/{customer}/activity
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.

Get an order's points

get

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.

Authorizations
X-Shopwaive-Access-TokenstringRequired

Your Shopwaive API key. Create it in the Shopwaive app under Settings > Develop > Shopwaive API keys. It starts with swak_.

Path parameters
orderstringRequired

The Shopify order id. The number, or the full id URL encoded, for example gid%3A%2F%2Fshopify%2FOrder%2F1234567890.

Example: 1234567890
Responses
200

The order's loyalty record.

application/json
get/api/loyalty/orders/{order}
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.

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.

Last updated