> 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/customer-api.md).

# Customer API

Read a customer's balance, set it, or add to it and take from it with the Shopwaive Customer API

The Customer API reads and changes a customer's Shopwaive balance. Every request needs your Shopwaive API key in the `X-Shopwaive-Access-Token` header and `shopify` in the `X-Shopwaive-Platform` header. To create a key, see the [Quick Start](https://api.shopwaive.com/classic/quick-start.md#get-your-api-keys).

| Request                              | What it does                                                  |
| ------------------------------------ | ------------------------------------------------------------- |
| `GET /api/customer/{customer_email}` | Returns the customer's balance.                               |
| `POST /api/customer`                 | Sets the balance to a value.                                  |
| `PUT /api/customer`                  | Adds to the balance, or takes from it with a negative amount. |

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

## `GET` customer endpoint

Returns the customer's balance. Shopwaive reads the email address in lower case.

## Get a customer's balance

> Returns the customer's balance. Add \`activity=true\`, \`orders=true\` or \`offers=true\` to include more.\
> \
> A customer with no Shopwaive balance yet returns HTTP 200 with \`balance\` 0 and a \`status\` that says the customer does not exist.<br>

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Customer API","description":"Read a customer's balance, set it, or add to it and take from it."}],"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":{"Platform":{"name":"X-Shopwaive-Platform","in":"header","required":true,"description":"Always `shopify`.","schema":{"type":"string","enum":["shopify"],"default":"shopify"}}},"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}$"}},"RateLimitLimit":{"description":"Requests allowed a second on this route.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests left in the current second.","schema":{"type":"integer"}},"RetryAfter":{"description":"Seconds to wait before you retry.","schema":{"type":"integer"}}},"schemas":{"CustomerBalance":{"type":"object","properties":{"status":{"type":"string","const":"success"},"customerid":{"description":"The customer's Shopify id.","type":["string","number"]},"email":{"type":"string"},"balance":{"description":"The balance, rounded to 2 decimals.","type":"number"},"currency":{"description":"The currency code of the balance (or of `isocode` when it was converted).","type":"string"},"expirationdate":{"description":"When the whole balance expires, if `expires` is `true`.","type":"string"},"expires":{"$ref":"#/components/schemas/Expires"},"activity":{"description":"With `activity=true`. Every entry of the balance.","type":"array","items":{"$ref":"#/components/schemas/Entry"}},"orders":{"description":"With `orders=true`. The orders saved with the balance.","type":"array","items":{"type":"object","additionalProperties":true}},"offers":{"description":"With `offers=true`. The customer's Budgets that can still be spent.","type":"object","properties":{"total":{"description":"The sum of what can still be spent.","type":"number"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}}}}}},"Expires":{"description":"`true` when the amount expires on `expirationdate`, else `false`. Sent and stored as text.","type":["string","boolean"]},"Entry":{"description":"One entry (action) of a balance, as Shopwaive stores it. Which fields are present depends on how the entry was made.","type":"object","additionalProperties":true,"properties":{"id":{"description":"The entry's id.","type":["string","number"]},"date":{"description":"When the entry was made or last changed.","type":"string"},"note":{"type":"string"},"type":{"description":"How the entry was made, for example `rest_api`.","type":"string"},"amount":{"description":"The amount the entry added (negative when it took).","type":["number","string"]},"expirationdate":{"type":"string"},"expires":{"$ref":"#/components/schemas/Expires"},"status":{"description":"For example `expired` or `redeemed`.","type":"string"},"media":{"type":"string"},"orderid":{"description":"The order of the latest spend from this entry.","type":["string","number"]},"lineitemid":{"description":"The order line that made this entry.","type":["string","number"]},"segment_query":{"type":"string"},"collectionids":{"type":"string"},"productids":{"type":"string"},"remaining":{"description":"What is left of the entry after earlier orders.","type":["number","string"]},"partial_amount":{"description":"What can be spent now, when the balance is lower than `remaining`.","type":["number","string"]},"validity":{"description":"Action API only. How long until the amount expires, in words: for example `expires in less than 3 months`, `expires in less than 24 hours`, `expired`, or `does not expire`.","type":"string"},"message":{"description":"Action API only. A note about this entry, for example why it does not expire or why it was not changed.","type":"string"},"transaction":{"description":"Not reliable. Do not use.","deprecated":true,"type":["string","number"]}}},"CustomerNotFound":{"type":"object","properties":{"status":{"type":"string","const":"Customer does not exist. Check case, all customers require lowercase"},"email":{"type":"string"},"balance":{"type":"number","const":0}}},"PlatformRefusedGet":{"description":"The X-Shopwaive-Platform header is missing or is not `shopify` (GET customer answers this with HTTP 200).","type":"object","properties":{"status":{"type":"string","const":"failed"},"message":{"type":"string","const":"Shopwaive API currently only supports stores on Shopify. Invalid X-Shopwaive-Platform header"}}},"KeyRefused":{"description":"A value that starts with swak_ was not accepted.","type":"object","properties":{"status":{"type":"string","const":"failed"},"reason":{"description":"Set only for a paused key (app_uninstalled: HTTP 401; the store uninstalled Shopwaive, and the key works again when the app is reinstalled) and for a key without the scope the request needs (missing_scope: HTTP 403).","type":"string","enum":["app_uninstalled","missing_scope"]},"scope":{"description":"With missing_scope. The scope the request needs: wallets:write, flow:trigger on POST /api/trigger, or wallets:read for a read by a key with flow:trigger and no wallets: scope.","type":"string"},"message":{"description":"Without reason: Invalid X-Shopwaive-Access-Token: followed by the reason: not-a-shopwaive-api-key, key-not-recognised, key-revoked or store-has-no-token. With reason: a sentence that says what to do.","type":"string"}}},"UnknownToken":{"description":"No key was sent, or Shopwaive does not know the token.","type":"object","properties":{"error":{"type":"string","const":"unknown_api_token"},"message":{"type":"string"}}},"RateLimited":{"type":"object","properties":{"error":{"type":"string"}}},"TemporarilyUnavailable":{"type":"object","properties":{"status":{"type":"string","const":"failed_temporary"},"message":{"type":"string"}}},"KeyCheckUnavailable":{"description":"A swak_ key could not be checked just now.","type":"object","properties":{"status":{"type":"string","const":"failed"},"message":{"type":"string","const":"Shopwaive API key lookup is temporarily unavailable. Retry."}}}},"responses":{"Unauthorized":{"description":"The API key was not accepted. A value that starts with `swak_` gets `status` `failed` and a `message` that names the reason. A key of a store that uninstalled Shopwaive is paused, not revoked: it gets `reason` `app_uninstalled` and works again when the app is reinstalled. No key, or a token Shopwaive does not know, gets `unknown_api_token`.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/KeyRefused"},{"$ref":"#/components/schemas/UnknownToken"}]}}}},"RateLimited":{"description":"Too many requests. Wait the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimited"}}}},"CredentialCheckUnavailable":{"description":"The key could not be checked just now. Nothing was changed. Retry.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TemporarilyUnavailable"},{"$ref":"#/components/schemas/KeyCheckUnavailable"}]}}}}}},"paths":{"/api/customer/{customer_email}":{"get":{"tags":["Customer API"],"operationId":"getCustomer","summary":"Get a customer's balance","description":"Returns the customer's balance. Add `activity=true`, `orders=true` or `offers=true` to include more.\n\nA customer with no Shopwaive balance yet returns HTTP 200 with `balance` 0 and a `status` that says the customer does not exist.\n","parameters":[{"name":"customer_email","in":"path","required":true,"description":"The customer's email address. Shopwaive reads it in lower case.","schema":{"type":"string","format":"email"}},{"name":"activity","in":"query","required":false,"description":"`true` adds `activity`: every entry of the balance.","schema":{"type":"string","enum":["true"]}},{"name":"orders","in":"query","required":false,"description":"`true` adds `orders`: the orders saved with the balance.","schema":{"type":"string","enum":["true"]}},{"name":"offers","in":"query","required":false,"description":"`true` adds `offers`: the customer's Budgets that can still be spent, with their total.","schema":{"type":"string","enum":["true"]}},{"name":"isocode","in":"query","required":false,"description":"A currency code, for example `EUR`. When it is not the store's currency, `balance` (and the amounts in `activity` and `offers`) are converted at Shopify's published exchange rate, and `currency` is that code. For a code Shopify does not list, the amounts are not converted and `currency` reads `Requested isocode currency not found`.\n","schema":{"type":"string"}},{"$ref":"#/components/parameters/Platform"}],"responses":{"200":{"description":"The customer's balance. Also HTTP 200 when the customer has no balance yet, and when the X-Shopwaive-Platform header is not `shopify`.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CustomerBalance"},{"$ref":"#/components/schemas/CustomerNotFound"},{"$ref":"#/components/schemas/PlatformRefusedGet"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"description":"The email address is not valid. The body is the plain text `Method Not Allowed`.","content":{"text/plain":{"schema":{"type":"string","const":"Method Not Allowed"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/CredentialCheckUnavailable"}}}}}}
```

### Query parameters

| key      | value                                                                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| activity | `true` adds `activity`: every entry of the balance.                                                                                                                  |
| orders   | `true` adds `orders`: the orders saved with the balance.                                                                                                             |
| offers   | `true` adds `offers`: the customer's Budgets that can still be spent, with their `total`.                                                                            |
| isocode  | A currency code, for example `EUR`. When it is not the store's currency, the amounts are converted at Shopify's published exchange rate and `currency` is that code. |

### Response body

| key            | value                                                                        |
| -------------- | ---------------------------------------------------------------------------- |
| status         | `success`                                                                    |
| customerid     | The customer's Shopify id                                                    |
| email          | The customer's email address                                                 |
| balance        | The balance, rounded to 2 decimals                                           |
| currency       | The currency code of the balance                                             |
| expirationdate | When the whole balance expires, if `expires` is `true`                       |
| expires        | `true` or `false`, as text                                                   |
| activity       | With `activity=true`: every entry of the balance                             |
| orders         | With `orders=true`: the orders saved with the balance                        |
| offers         | With `offers=true`: `total` and `items`, the Budgets that can still be spent |
| referralurl    | The customer's referral link, when the store's referral program is on        |

{% hint style="info" %}
A customer with no Shopwaive balance yet returns HTTP `200` with `balance` `0` and the `status` "Customer does not exist. Check case, all customers require lowercase".
{% endhint %}

## `POST` customer endpoint

Sets the customer's balance to `balance`. This changes a real balance in your store.

## Set a customer's balance

> Sets the customer's balance to \`balance\`. This changes a real balance in your store.\
> \
> An expiry date is saved only when the request has both \`expirationdate\` and \`expires\`.\
> \
> Send an \`Idempotency-Key\` header with a new value for each change. A retry with the same key gets the first answer and changes nothing again. Without the header, a request made with a Shopwaive API key returns 400 \`idempotency\_key\_required\` and changes nothing.<br>

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Customer API","description":"Read a customer's balance, set it, or add to it and take from it."}],"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":{"Platform":{"name":"X-Shopwaive-Platform","in":"header","required":true,"description":"Always `shopify`.","schema":{"type":"string","enum":["shopify"],"default":"shopify"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Required with a Shopwaive API key. A key you choose for this change: 1 to 255 printable ASCII characters, with no space at either end. A UUID is a good choice. Use a new key for each change, and send the same key again to retry: Shopwaive answers with the first answer and changes nothing again. Without it, the request returns 400 `idempotency_key_required` and changes nothing.\n","schema":{"type":"string","minLength":1,"maxLength":255}}},"schemas":{"SetBalanceRequest":{"type":"object","required":["customer_email","balance"],"properties":{"customer_email":{"description":"The customer's email address.","type":"string","format":"email"},"balance":{"description":"The new balance.","type":["number","string"]},"note":{"description":"A note saved with the entry.","type":"string"},"expirationdate":{"description":"When the balance expires, for example `2028-04-21` or `April 21, 2028`. Needs `expires`.","type":"string"},"expires":{"$ref":"#/components/schemas/Expires"}}},"Expires":{"description":"`true` when the amount expires on `expirationdate`, else `false`. Sent and stored as text.","type":["string","boolean"]},"SetBalanceResult":{"type":"object","properties":{"status":{"type":"string","const":"success"},"customerid":{"type":["string","number"]},"email":{"type":"string"},"note":{"type":"string"},"previous":{"description":"The balance before this request.","type":"number"},"balance":{"description":"The balance after this request.","type":"number"},"id":{"description":"The id of the entry this request made. Use it with the Action API.","type":["string","number"]},"expirationdate":{"type":"string"},"expires":{"$ref":"#/components/schemas/Expires"}}},"NotANumber":{"type":"object","properties":{"status":{"type":"string","enum":["NaN. Invalid balance value","NaN. Invalid amount value"]}}},"PlatformRefused":{"type":"object","properties":{"status":{"type":"string","const":"Shopwaive API currently only supports stores on Shopify. Invalid X-Shopwaive-Platform header."}}},"IdempotencyKeyMissing":{"description":"A request made with a Shopwaive API key, or a deposit to a customer segment, was sent without an Idempotency-Key header.","type":"object","properties":{"status":{"type":"string","const":"failed"},"reason":{"type":"string","const":"idempotency_key_required"},"header":{"type":"string","const":"Idempotency-Key"},"message":{"type":"string"}}},"IdempotencyRefused":{"type":"object","properties":{"status":{"type":"string","enum":["IDEMPOTENCY_KEY_INVALID","IDEMPOTENCY_CONCURRENT_REQUEST","IDEMPOTENCY_KEY_PARAMETER_MISMATCH"]},"message":{"type":"string"}}},"KeyRefused":{"description":"A value that starts with swak_ was not accepted.","type":"object","properties":{"status":{"type":"string","const":"failed"},"reason":{"description":"Set only for a paused key (app_uninstalled: HTTP 401; the store uninstalled Shopwaive, and the key works again when the app is reinstalled) and for a key without the scope the request needs (missing_scope: HTTP 403).","type":"string","enum":["app_uninstalled","missing_scope"]},"scope":{"description":"With missing_scope. The scope the request needs: wallets:write, flow:trigger on POST /api/trigger, or wallets:read for a read by a key with flow:trigger and no wallets: scope.","type":"string"},"message":{"description":"Without reason: Invalid X-Shopwaive-Access-Token: followed by the reason: not-a-shopwaive-api-key, key-not-recognised, key-revoked or store-has-no-token. With reason: a sentence that says what to do.","type":"string"}}},"UnknownToken":{"description":"No key was sent, or Shopwaive does not know the token.","type":"object","properties":{"error":{"type":"string","const":"unknown_api_token"},"message":{"type":"string"}}},"RateLimited":{"type":"object","properties":{"error":{"type":"string"}}},"IdempotencyPending":{"type":"object","properties":{"status":{"type":"string","const":"pending"},"code":{"type":"string","enum":["IDEMPOTENCY_OUTCOME_PENDING","IDEMPOTENCY_STORE_UNAVAILABLE"]},"message":{"type":"string"}}},"TemporarilyUnavailable":{"type":"object","properties":{"status":{"type":"string","const":"failed_temporary"},"message":{"type":"string"}}},"KeyCheckUnavailable":{"description":"A swak_ key could not be checked just now.","type":"object","properties":{"status":{"type":"string","const":"failed"},"message":{"type":"string","const":"Shopwaive API key lookup is temporarily unavailable. Retry."}}}},"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}$"}},"IdempotentReplayed":{"description":"`true` when this is the recorded answer to an earlier request with the same key or content. Nothing was changed again.","schema":{"type":"string","enum":["true"]}},"RetryAfter":{"description":"Seconds to wait before you retry.","schema":{"type":"integer"}}},"responses":{"PlatformRefused":{"description":"The X-Shopwaive-Platform header is missing or is not `shopify`. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformRefused"}}}},"IdempotencyKeyMissingOrInvalid":{"description":"The Idempotency-Key header is missing (a request made with a Shopwaive API key needs one) or is not valid. Nothing was changed.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/IdempotencyKeyMissing"},{"$ref":"#/components/schemas/IdempotencyRefused"}]}}}},"Unauthorized":{"description":"The API key was not accepted. A value that starts with `swak_` gets `status` `failed` and a `message` that names the reason. A key of a store that uninstalled Shopwaive is paused, not revoked: it gets `reason` `app_uninstalled` and works again when the app is reinstalled. No key, or a token Shopwaive does not know, gets `unknown_api_token`.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/KeyRefused"},{"$ref":"#/components/schemas/UnknownToken"}]}}}},"KeyMissingScope":{"description":"The API key does not hold the scope this request needs, and `scope` names it. A request that changes a balance needs **Change balances through the REST API (wallets:write)**. `POST /api/trigger` needs `wallets:write` or **Start Shopify Flow from another store (flow:trigger)**: a key with neither is refused with `scope` `flow:trigger`. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRefused"}}}},"IdempotencyBusy":{"description":"A request with the same key is still running. Retry after the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdempotencyRefused"}}}},"IdempotencyMismatch":{"description":"This Idempotency-Key was already used with different fields. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdempotencyRefused"}}}},"RateLimited":{"description":"Too many requests. Wait the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimited"}}}},"RetryLater":{"description":"The key could not be checked, or the outcome of the request is not known yet. Retry the same request, with the same Idempotency-Key, after the seconds in Retry-After. Shopwaive checks its ledger before it acts on it again.\n","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/IdempotencyPending"},{"$ref":"#/components/schemas/TemporarilyUnavailable"},{"$ref":"#/components/schemas/KeyCheckUnavailable"}]}}}}}},"paths":{"/api/customer":{"post":{"tags":["Customer API"],"operationId":"setCustomerBalance","summary":"Set a customer's balance","description":"Sets the customer's balance to `balance`. This changes a real balance in your store.\n\nAn expiry date is saved only when the request has both `expirationdate` and `expires`.\n\nSend an `Idempotency-Key` header with a new value for each change. A retry with the same key gets the first answer and changes nothing again. Without the header, a request made with a Shopwaive API key returns 400 `idempotency_key_required` and changes nothing.\n","parameters":[{"$ref":"#/components/parameters/Platform"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetBalanceRequest"}}}},"responses":{"200":{"description":"The balance was set. Also HTTP 200 with only a `status` when `balance` is not a number.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SetBalanceResult"},{"$ref":"#/components/schemas/NotANumber"}]}}}},"201":{"$ref":"#/components/responses/PlatformRefused"},"400":{"$ref":"#/components/responses/IdempotencyKeyMissingOrInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/KeyMissingScope"},"405":{"description":"The email address is not valid, or Shopwaive sent the set but could not read its result: the balance may have been set, so read it before you send it again. The body is the plain text `Method Not Allowed`.","content":{"text/plain":{"schema":{"type":"string","const":"Method Not Allowed"}}}},"409":{"$ref":"#/components/responses/IdempotencyBusy"},"422":{"$ref":"#/components/responses/IdempotencyMismatch"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/RetryLater"}}}}}}
```

### Request body

| key               | value                                                                  |
| ----------------- | ---------------------------------------------------------------------- |
| customer\_email\* | The customer's email address                                           |
| balance\*         | The new balance                                                        |
| note              | A note saved with the entry                                            |
| expirationdate    | When the balance expires, for example `2028-04-21` or `April 21, 2028` |
| expires           | `true` or `false`                                                      |

### Response body

| key            | value                                                                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| status         | `success`                                                                                                                                             |
| customerid     | The customer's Shopify id                                                                                                                             |
| email          | The customer's email address                                                                                                                          |
| note           | The note                                                                                                                                              |
| previous       | The balance before the request                                                                                                                        |
| balance        | The balance after the request                                                                                                                         |
| id             | The id of the entry the request made. Use it with the [Action API](https://api.shopwaive.com/classic/reference/rest-api-documentation/action-api.md). |
| expirationdate | The expiry date                                                                                                                                       |
| expires        | `true` or `false`                                                                                                                                     |

{% hint style="info" %}
An expiry date is saved only when the request has both `expirationdate` and `expires`.
{% endhint %}

## `PUT` customer endpoint

Adds `amount` to the customer's balance. A negative `amount` takes it away. This changes a real balance in your store.

## Add to or take from a customer's balance

> Adds \`amount\` to the customer's balance. A negative \`amount\` takes it away. This changes a real balance in your store.\
> \
> To give the same amount to every customer of a Shopify customer segment, send \`segment\_query\` in place of \`customer\_email\`.\
> \
> An expiry date is saved only when the request has both \`expirationdate\` and \`expires\`. When the store uses \*\*Multiple expiry dates\*\* (Settings > Theme > Expiration), the date applies to this amount. With \*\*Single expiry date\*\*, it is the expiry date of the whole balance.\
> \
> Send an \`Idempotency-Key\` header with a new value for each change. A retry with the same key gets the first answer and changes nothing again. Without the header, a request made with a Shopwaive API key returns 400 \`idempotency\_key\_required\` and changes nothing.\
> \
> A deposit to a customer segment (\`segment\_query\`) is available on the Shopwaive Checkout plan (otherwise 403 \`plan\_required\`). A store can send one a minute (429 \`bulk\_too\_soon\`), and each counts as 1,000 rows of the store's 10,000 a day, UTC (429 \`bulk\_daily\_limit\`). A retry with the same \`Idempotency-Key\` the same day is not counted again.<br>

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Customer API","description":"Read a customer's balance, set it, or add to it and take from it."}],"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":{"Platform":{"name":"X-Shopwaive-Platform","in":"header","required":true,"description":"Always `shopify`.","schema":{"type":"string","enum":["shopify"],"default":"shopify"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Required with a Shopwaive API key. A key you choose for this change: 1 to 255 printable ASCII characters, with no space at either end. A UUID is a good choice. Use a new key for each change, and send the same key again to retry: Shopwaive answers with the first answer and changes nothing again. Without it, the request returns 400 `idempotency_key_required` and changes nothing.\n","schema":{"type":"string","minLength":1,"maxLength":255}}},"schemas":{"AdjustBalanceRequest":{"type":"object","required":["amount"],"description":"Send `customer_email`, or `segment_query` in its place.","properties":{"customer_email":{"description":"The customer's email address. Leave it out when you send `segment_query`.","type":"string","format":"email"},"amount":{"description":"The amount to add. A negative amount takes it away.","type":["number","string"]},"note":{"description":"A note saved with the entry.","type":"string"},"expirationdate":{"description":"When the amount expires, for example `2028-04-21` or `April 21, 2028`. Needs `expires`.","type":"string"},"expires":{"$ref":"#/components/schemas/Expires"},"media":{"description":"A link to an image saved with the entry.","type":"string","format":"uri"},"segment_query":{"description":"A Shopify customer segment query, for example `customer_tags CONTAINS 'VIP'`. Every customer in the segment gets the amount.","type":"string"},"collectionids":{"description":"Shopify collection ids where the amount can be spent, separated by commas.","type":"string"},"productids":{"description":"Shopify product ids where the amount can be spent, separated by commas.","type":"string"}}},"Expires":{"description":"`true` when the amount expires on `expirationdate`, else `false`. Sent and stored as text.","type":["string","boolean"]},"AdjustBalanceResult":{"type":"object","properties":{"status":{"type":"string","const":"success"},"customerid":{"type":["string","number"]},"email":{"type":"string"},"note":{"type":"string"},"previous":{"description":"The balance before this request.","type":"number"},"transaction":{"description":"The amount added (negative when taken).","type":"number"},"balance":{"description":"The balance after this request (never below 0).","type":"number"},"id":{"description":"The id of the entry this request made. Use it with the Action API.","type":["string","number"]},"expirationdate":{"type":"string"},"expires":{"$ref":"#/components/schemas/Expires"},"media":{"type":"string"}}},"NotANumber":{"type":"object","properties":{"status":{"type":"string","enum":["NaN. Invalid balance value","NaN. Invalid amount value"]}}},"PlatformRefused":{"type":"object","properties":{"status":{"type":"string","const":"Shopwaive API currently only supports stores on Shopify. Invalid X-Shopwaive-Platform header."}}},"IdempotencyKeyMissing":{"description":"A request made with a Shopwaive API key, or a deposit to a customer segment, was sent without an Idempotency-Key header.","type":"object","properties":{"status":{"type":"string","const":"failed"},"reason":{"type":"string","const":"idempotency_key_required"},"header":{"type":"string","const":"Idempotency-Key"},"message":{"type":"string"}}},"IdempotencyRefused":{"type":"object","properties":{"status":{"type":"string","enum":["IDEMPOTENCY_KEY_INVALID","IDEMPOTENCY_CONCURRENT_REQUEST","IDEMPOTENCY_KEY_PARAMETER_MISMATCH"]},"message":{"type":"string"}}},"KeyRefused":{"description":"A value that starts with swak_ was not accepted.","type":"object","properties":{"status":{"type":"string","const":"failed"},"reason":{"description":"Set only for a paused key (app_uninstalled: HTTP 401; the store uninstalled Shopwaive, and the key works again when the app is reinstalled) and for a key without the scope the request needs (missing_scope: HTTP 403).","type":"string","enum":["app_uninstalled","missing_scope"]},"scope":{"description":"With missing_scope. The scope the request needs: wallets:write, flow:trigger on POST /api/trigger, or wallets:read for a read by a key with flow:trigger and no wallets: scope.","type":"string"},"message":{"description":"Without reason: Invalid X-Shopwaive-Access-Token: followed by the reason: not-a-shopwaive-api-key, key-not-recognised, key-revoked or store-has-no-token. With reason: a sentence that says what to do.","type":"string"}}},"UnknownToken":{"description":"No key was sent, or Shopwaive does not know the token.","type":"object","properties":{"error":{"type":"string","const":"unknown_api_token"},"message":{"type":"string"}}},"PlanRequired":{"description":"A deposit to a customer segment from a store that is not on the Shopwaive Checkout plan. Nothing was changed.","type":"object","properties":{"status":{"type":"string","const":"failed"},"reason":{"type":"string","const":"plan_required"},"plan":{"type":"string","const":"Shopwaive Checkout"},"message":{"type":"string"}}},"RateLimited":{"type":"object","properties":{"error":{"type":"string"}}},"BulkLimited":{"description":"A deposit to a customer segment over the store's limits. Nothing was changed.","type":"object","properties":{"status":{"type":"string","const":"failed"},"reason":{"type":"string","enum":["bulk_too_soon","bulk_daily_limit"]},"limit":{"type":"string"},"rows_used_today":{"description":"With bulk_daily_limit.","type":"integer"},"rows_requested":{"description":"With bulk_daily_limit.","type":"integer"},"message":{"type":"string"}}},"IdempotencyPending":{"type":"object","properties":{"status":{"type":"string","const":"pending"},"code":{"type":"string","enum":["IDEMPOTENCY_OUTCOME_PENDING","IDEMPOTENCY_STORE_UNAVAILABLE"]},"message":{"type":"string"}}},"TemporarilyUnavailable":{"type":"object","properties":{"status":{"type":"string","const":"failed_temporary"},"message":{"type":"string"}}},"KeyCheckUnavailable":{"description":"A swak_ key could not be checked just now.","type":"object","properties":{"status":{"type":"string","const":"failed"},"message":{"type":"string","const":"Shopwaive API key lookup is temporarily unavailable. Retry."}}},"BulkCheckUnavailable":{"description":"A deposit to a customer segment could not be checked just now. Nothing was scheduled. Retry in a minute with the same Idempotency-Key.","type":"object","properties":{"status":{"type":"string","const":"failed"},"reason":{"type":"string","const":"bulk_check_unavailable"},"message":{"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}$"}},"IdempotentReplayed":{"description":"`true` when this is the recorded answer to an earlier request with the same key or content. Nothing was changed again.","schema":{"type":"string","enum":["true"]}},"RetryAfter":{"description":"Seconds to wait before you retry.","schema":{"type":"integer"}}},"responses":{"PlatformRefused":{"description":"The X-Shopwaive-Platform header is missing or is not `shopify`. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformRefused"}}}},"IdempotencyKeyMissingOrInvalid":{"description":"The Idempotency-Key header is missing (a request made with a Shopwaive API key needs one) or is not valid. Nothing was changed.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/IdempotencyKeyMissing"},{"$ref":"#/components/schemas/IdempotencyRefused"}]}}}},"Unauthorized":{"description":"The API key was not accepted. A value that starts with `swak_` gets `status` `failed` and a `message` that names the reason. A key of a store that uninstalled Shopwaive is paused, not revoked: it gets `reason` `app_uninstalled` and works again when the app is reinstalled. No key, or a token Shopwaive does not know, gets `unknown_api_token`.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/KeyRefused"},{"$ref":"#/components/schemas/UnknownToken"}]}}}},"IdempotencyBusy":{"description":"A request with the same key is still running. Retry after the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdempotencyRefused"}}}},"IdempotencyMismatch":{"description":"This Idempotency-Key was already used with different fields. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdempotencyRefused"}}}}}},"paths":{"/api/customer":{"put":{"tags":["Customer API"],"operationId":"adjustCustomerBalance","summary":"Add to or take from a customer's balance","description":"Adds `amount` to the customer's balance. A negative `amount` takes it away. This changes a real balance in your store.\n\nTo give the same amount to every customer of a Shopify customer segment, send `segment_query` in place of `customer_email`.\n\nAn expiry date is saved only when the request has both `expirationdate` and `expires`. When the store uses **Multiple expiry dates** (Settings > Theme > Expiration), the date applies to this amount. With **Single expiry date**, it is the expiry date of the whole balance.\n\nSend an `Idempotency-Key` header with a new value for each change. A retry with the same key gets the first answer and changes nothing again. Without the header, a request made with a Shopwaive API key returns 400 `idempotency_key_required` and changes nothing.\n\nA deposit to a customer segment (`segment_query`) is available on the Shopwaive Checkout plan (otherwise 403 `plan_required`). A store can send one a minute (429 `bulk_too_soon`), and each counts as 1,000 rows of the store's 10,000 a day, UTC (429 `bulk_daily_limit`). A retry with the same `Idempotency-Key` the same day is not counted again.\n","parameters":[{"$ref":"#/components/parameters/Platform"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustBalanceRequest"}}}},"responses":{"200":{"description":"The amount was added or taken. Also HTTP 200 with only a `status` when `amount` is not a number.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AdjustBalanceResult"},{"$ref":"#/components/schemas/NotANumber"}]}}}},"201":{"$ref":"#/components/responses/PlatformRefused"},"400":{"$ref":"#/components/responses/IdempotencyKeyMissingOrInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The API key cannot change balances (`missing_scope`), or a deposit to a customer segment came from a store that is not on the Shopwaive Checkout plan (`plan_required`). Nothing was changed.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/KeyRefused"},{"$ref":"#/components/schemas/PlanRequired"}]}}}},"405":{"description":"The request has neither a valid email address nor a segment query, or Shopwaive sent the change but could not read its result: it may have been made, a deposit to a customer segment included, so read the balance before you send it again. The body is the plain text `Method Not Allowed`. A deposit the store's own limit refused, or one that was not recorded, answers JSON with `status` `failed_store_limit` or `failed_balance_service` and a `message`, and nothing was changed.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["failed_store_limit","failed_balance_service"]},"message":{"type":"string"}}}},"text/plain":{"schema":{"type":"string","const":"Method Not Allowed"}}}},"409":{"$ref":"#/components/responses/IdempotencyBusy"},"422":{"$ref":"#/components/responses/IdempotencyMismatch"},"429":{"description":"Too many requests, or a deposit to a customer segment over the store's limits (`bulk_too_soon`, `bulk_daily_limit`). Nothing was changed. Wait the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RateLimited"},{"$ref":"#/components/schemas/BulkLimited"}]}}}},"503":{"description":"The key could not be checked, the outcome of the request is not known yet, or a deposit to a customer segment could not be checked (`bulk_check_unavailable`: nothing was scheduled). Retry the same request, with the same Idempotency-Key, after the seconds in Retry-After. Shopwaive checks its ledger before it acts on it again.\n","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/IdempotencyPending"},{"$ref":"#/components/schemas/TemporarilyUnavailable"},{"$ref":"#/components/schemas/KeyCheckUnavailable"},{"$ref":"#/components/schemas/BulkCheckUnavailable"}]}}}}}}}}}
```

### Request body

| key               | value                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| customer\_email\* | The customer's email address. Leave it out when you send `segment_query`.                                                                                                                                                                                                                                                                                                                                                    |
| amount\*          | The amount to add. A negative amount takes it away.                                                                                                                                                                                                                                                                                                                                                                          |
| note              | A note saved with the entry                                                                                                                                                                                                                                                                                                                                                                                                  |
| expirationdate    | When the amount expires, for example `2028-04-21` or `April 21, 2028`                                                                                                                                                                                                                                                                                                                                                        |
| expires           | `true` or `false`                                                                                                                                                                                                                                                                                                                                                                                                            |
| media             | A link to an image saved with the entry                                                                                                                                                                                                                                                                                                                                                                                      |
| segment\_query    | A Shopify customer segment query, for example `customer_tags CONTAINS 'VIP'`. Every customer in the segment gets the amount. A segment deposit needs the Shopwaive Checkout plan and an `Idempotency-Key` header. It counts as 1,000 rows of the store's 10,000 a day, and a store can send one a minute: see [Segment deposits](https://api.shopwaive.com/classic/reference/shopwaive-api-rate-limits.md#segment-deposits). |
| collectionids     | Shopify collection ids where the amount can be spent, separated by commas                                                                                                                                                                                                                                                                                                                                                    |
| productids        | Shopify product ids where the amount can be spent, separated by commas                                                                                                                                                                                                                                                                                                                                                       |

### Response body

| key            | value                                                                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| status         | `success`                                                                                                                                             |
| customerid     | The customer's Shopify id                                                                                                                             |
| email          | The customer's email address                                                                                                                          |
| note           | The note                                                                                                                                              |
| previous       | The balance before the request                                                                                                                        |
| transaction    | The amount added (negative when taken)                                                                                                                |
| balance        | The balance after the request. It never goes below 0.                                                                                                 |
| id             | The id of the entry the request made. Use it with the [Action API](https://api.shopwaive.com/classic/reference/rest-api-documentation/action-api.md). |
| expirationdate | The expiry date                                                                                                                                       |
| expires        | `true` or `false`                                                                                                                                     |
| media          | The media link                                                                                                                                        |

{% hint style="info" %}
An expiry date is saved only when the request has both `expirationdate` and `expires`. When the store uses **Multiple expiry dates** (**Settings** > **Balances** > **Expiration**), the date applies to this amount. With **Single expiry date**, it is the expiry date of the whole balance.
{% endhint %}

## Retry safely

`POST` and `PUT` need an `Idempotency-Key` header: a key you choose, 1 to 255 printable ASCII characters with no space at either end. A UUID is a good choice. Use a new key for each change. Send the same request with the same key again and Shopwaive answers with the first answer, with the header `Idempotent-Replayed: true`. Nothing changes twice. To make two equal changes on purpose, send each with its own key.

A request made with a Shopwaive API key and no `Idempotency-Key` returns HTTP `400` with the reason `idempotency_key_required`, and nothing is changed.

| Status | Body                                 | When                                                                                                    |
| ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `400`  | `idempotency_key_required`           | The request was made with a Shopwaive API key and has no `Idempotency-Key` header. Nothing was changed. |
| `400`  | `IDEMPOTENCY_KEY_INVALID`            | The key is not 1 to 255 printable ASCII characters, or it starts or ends with a space.                  |
| `409`  | `IDEMPOTENCY_CONCURRENT_REQUEST`     | A request with the same key is still running. Retry after `Retry-After`.                                |
| `422`  | `IDEMPOTENCY_KEY_PARAMETER_MISMATCH` | The key was already used with different fields.                                                         |
| `503`  | `pending`                            | The outcome is not known yet. Retry with the same key after `Retry-After`.                              |

## Many customers at once

Send one `PUT /api/customer` request for each customer, or send `segment_query` to reach a whole customer segment (on the Shopwaive Checkout plan: see [Segment deposits](https://api.shopwaive.com/classic/reference/shopwaive-api-rate-limits.md#segment-deposits)). For anything else, contact <support@shopwaive.com>.
