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

# Action API

Read, update and delete the entries (actions) that make up a customer's balance with the Shopwaive Action API

Every change to a balance is saved as an entry, which the API calls an action. The Action API reads entries, changes an entry's note, expiry or media, and deletes entries. Every request needs your Shopwaive API key in the `X-Shopwaive-Access-Token` header and `shopify` in the `X-Shopwaive-Platform` header. `POST` and `DELETE` also need an `Idempotency-Key` header: see [Retry safely](#retry-safely).

| Request                         | What it does                                                                |
| ------------------------------- | --------------------------------------------------------------------------- |
| `GET /api/actions`              | Searches entries by customer and date.                                      |
| `GET /api/action/{actionid}`    | Returns the entries with this id.                                           |
| `POST /api/action/{actionid}`   | Changes an entry's note, expiry or media.                                   |
| `DELETE /api/action/{actionid}` | Deletes the entries with this id, and reverses their amount on the balance. |

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

An entry's id is the `id` of the [Customer API](https://api.shopwaive.com/classic/reference/rest-api-documentation/customer-api.md) answer that made it, or the `id` of an entry in `activity`.

{% hint style="info" %}
To give a customer several amounts that expire on different dates, choose **Multiple expiry dates** in the Shopwaive app under **Settings** > **Balances** > **Expiration**. Then send each amount with its own `expirationdate` and `expires` in a [`PUT` customer](https://api.shopwaive.com/classic/reference/rest-api-documentation/customer-api.md#put-customer-endpoint) request.
{% endhint %}

## `GET` actions endpoint

Searches entries. Filter by customer with `email` and by date with `created_at_min` and `created_at_max`.

## Search entries

> Returns entries (actions) of the store's balances. Filter by customer with \`email\` and by date with \`created\_at\_min\` and \`created\_at\_max\`.\
> \
> An \`email\` that is not a valid address is ignored, and entries of every customer are returned.<br>

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Action API","description":"Read, update and delete the entries (actions) that make up a customer's balance."}],"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}$"}},"RetryAfter":{"description":"Seconds to wait before you retry.","schema":{"type":"integer"}}},"schemas":{"ActionList":{"type":"object","properties":{"actions":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}}}},"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"]}}},"Expires":{"description":"`true` when the amount expires on `expirationdate`, else `false`. Sent and stored as text.","type":["string","boolean"]},"PlatformRefused":{"type":"object","properties":{"status":{"type":"string","const":"Shopwaive API currently only supports stores on Shopify. Invalid X-Shopwaive-Platform header."}}},"DateRefused":{"type":"object","properties":{"status":{"type":"string","enum":["Invalid created_at_min date format","Invalid created_at_max date format"]}}},"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"}}},"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"}}},"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":{"PlatformRefused":{"description":"The X-Shopwaive-Platform header is missing or is not `shopify`. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformRefused"}}}},"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/actions":{"get":{"tags":["Action API"],"operationId":"listActions","summary":"Search entries","description":"Returns entries (actions) of the store's balances. Filter by customer with `email` and by date with `created_at_min` and `created_at_max`.\n\nAn `email` that is not a valid address is ignored, and entries of every customer are returned.\n","parameters":[{"name":"email","in":"query","required":false,"description":"Only this customer's entries.","schema":{"type":"string","format":"email"}},{"name":"created_at_min","in":"query","required":false,"description":"Only entries from this date on, for example `2026-10-01T00:00:00Z`.","schema":{"type":"string"}},{"name":"created_at_max","in":"query","required":false,"description":"Only entries up to this date. Without it, entries up to now.","schema":{"type":"string"}},{"$ref":"#/components/parameters/Platform"}],"responses":{"200":{"description":"The entries found. `actions` is empty when none match.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionList"}}}},"201":{"$ref":"#/components/responses/PlatformRefused"},"401":{"description":"A date is not valid (`status` names which), or the API key was not accepted.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DateRefused"},{"$ref":"#/components/schemas/UnknownToken"},{"$ref":"#/components/schemas/KeyRefused"}]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/CredentialCheckUnavailable"}}}}}}
```

{% code overflow="wrap" %}

```bash
curl --location 'https://app.shopwaive.com/api/actions?email=customer@example.com&created_at_min=2026-10-01T00:00:00Z&created_at_max=2026-10-26T23:59:59Z' \
--header 'X-Shopwaive-Access-Token: swak_EXAMPLEKEY000000000000000000000000000000' \
--header 'X-Shopwaive-Platform: shopify'
```

{% endcode %}

{% hint style="warning" %}
An `email` that is not a valid address is ignored, and entries of every customer are returned. A date that cannot be read returns HTTP `401` with `status` "Invalid created\_at\_min date format" (or `created_at_max`).
{% endhint %}

## `GET` action endpoint

Returns the entries with this id in `actions`. The list is empty when no entry has it.

## Get an entry

> Returns the entries with this id. \`actions\` is empty when none has it.

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Action API","description":"Read, update and delete the entries (actions) that make up a customer's balance."}],"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}$"}},"RetryAfter":{"description":"Seconds to wait before you retry.","schema":{"type":"integer"}}},"schemas":{"ActionList":{"type":"object","properties":{"actions":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}}}},"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"]}}},"Expires":{"description":"`true` when the amount expires on `expirationdate`, else `false`. Sent and stored as text.","type":["string","boolean"]},"PlatformRefused":{"type":"object","properties":{"status":{"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":{"PlatformRefused":{"description":"The X-Shopwaive-Platform header is missing or is not `shopify`. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformRefused"}}}},"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/action/{actionid}":{"get":{"tags":["Action API"],"operationId":"getAction","summary":"Get an entry","description":"Returns the entries with this id. `actions` is empty when none has it.","parameters":[{"$ref":"#/components/parameters/Platform"}],"responses":{"200":{"description":"The entries with this id.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionList"}}}},"201":{"$ref":"#/components/responses/PlatformRefused"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/CredentialCheckUnavailable"}}}}}}
```

### The fields of an entry

Which fields an entry has depends on how it was made.

| key             | value                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| id              | The entry's id                                                                                                           |
| date            | When the entry was made or last changed                                                                                  |
| note            | The entry's note                                                                                                         |
| type            | How the entry was made, for example `rest_api`                                                                           |
| amount          | The amount the entry added (negative when it took)                                                                       |
| expirationdate  | When the amount expires, if `expires` is `true`                                                                          |
| expires         | `true` or `false`, as text                                                                                               |
| status          | For example `expired` or `redeemed`                                                                                      |
| media           | A media link                                                                                                             |
| orderid         | The order of the latest spend from this entry                                                                            |
| lineitemid      | The order line that made this entry                                                                                      |
| segment\_query  | The customer segment query the entry was made with                                                                       |
| collectionids   | Collection ids where the amount can be spent                                                                             |
| productids      | Product ids where the amount can be spent                                                                                |
| remaining       | What is left of the entry after earlier orders                                                                           |
| partial\_amount | What can be spent now, when the balance is lower than `remaining`                                                        |
| validity        | How long until the amount expires, in words, for example `expires in less than 3 months`, `expired` or `does not expire` |
| message         | A note about the entry, for example why it does not expire                                                               |

{% hint style="info" %}
An entry has an expiry only when its `amount` is above 0 and `expires` is `true`. Otherwise `validity` is `does not expire`.
{% endhint %}

## `POST` action endpoint

Changes an entry's note, expiry or media link. It does not change any amount or balance.

## Update an entry's note, expiry or media

> Changes the note, the expiry or the media link of an entry. It does not change any amount or balance.\
> \
> An expiry is changed only when the request has both \`expirationdate\` and \`expires\`. An expired entry cannot be changed.\
> \
> An answer of HTTP 200 with the plain text \`OK\` means the update was sent for processing. Read the entry again with GET to see the change.<br>

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Action API","description":"Read, update and delete the entries (actions) that make up a customer's balance."}],"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":{"ActionUpdateRequest":{"type":"object","properties":{"note":{"description":"The new note.","type":"string"},"expirationdate":{"description":"The new expiry date, for example `2028-04-21` or `April 21, 2028`. Needs `expires`.","type":"string"},"expires":{"$ref":"#/components/schemas/Expires"},"media":{"description":"A new link to an image.","type":"string","format":"uri"}}},"Expires":{"description":"`true` when the amount expires on `expirationdate`, else `false`. Sent and stored as text.","type":["string","boolean"]},"ActionList":{"type":"object","properties":{"actions":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}}}},"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"]}}},"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"}}},"MessageOnly":{"type":"object","properties":{"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"}}}}}},"paths":{"/api/action/{actionid}":{"post":{"tags":["Action API"],"operationId":"updateAction","summary":"Update an entry's note, expiry or media","description":"Changes the note, the expiry or the media link of an entry. It does not change any amount or balance.\n\nAn expiry is changed only when the request has both `expirationdate` and `expires`. An expired entry cannot be changed.\n\nAn answer of HTTP 200 with the plain text `OK` means the update was sent for processing. Read the entry again with GET to see the change.\n","parameters":[{"$ref":"#/components/parameters/Platform"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionUpdateRequest"}}}},"responses":{"200":{"description":"Sent for processing, with the plain text `OK`. When an entry with this id has expired, the answer is JSON that lists it with a `message`, and it is not changed.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"text/plain":{"schema":{"type":"string","const":"OK"}},"application/json":{"schema":{"$ref":"#/components/schemas/ActionList"}}}},"201":{"$ref":"#/components/responses/PlatformRefused"},"400":{"$ref":"#/components/responses/IdempotencyKeyMissingOrInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/KeyMissingScope"},"405":{"description":"No entry has this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageOnly"}}}},"409":{"$ref":"#/components/responses/IdempotencyBusy"},"422":{"$ref":"#/components/responses/IdempotencyMismatch"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"The key could not be checked, or the outcome of the request is not known yet (the update may or may not have been queued). Read the entry with GET, then retry the same request, with the same Idempotency-Key, after the seconds in Retry-After.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/IdempotencyPending"},{"$ref":"#/components/schemas/TemporarilyUnavailable"},{"$ref":"#/components/schemas/KeyCheckUnavailable"}]}}}}}}}}}
```

### Request body

| key            | value                                                             |
| -------------- | ----------------------------------------------------------------- |
| note           | The new note                                                      |
| expirationdate | The new expiry date, for example `2028-04-21` or `April 21, 2028` |
| expires        | `true` or `false`                                                 |
| media          | A new media link                                                  |

Send only the fields you want to change. An expiry is changed only when the request has both `expirationdate` and `expires`.

### Answer

| Status | Body                                                                              | When                                                                                   |
| ------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `200`  | The plain text `OK`                                                               | The update was sent for processing. Read the entry again with `GET` to see the change. |
| `200`  | `actions`, each with `message` "action has already expired and cannot be updated" | An entry with this id has expired. It is not changed.                                  |
| `405`  | `message` "Failed. No document found or malformed request body"                   | No entry has this id.                                                                  |

## `DELETE` action endpoint

Deletes the entries with this id. This changes real balances in your store.

When a deleted entry added or took an amount, and it is not marked redeemed or expired, Shopwaive asks for that amount to be reversed on the balance: only `remaining` when it is above 0 and below the amount, otherwise the whole amount. Read the customer's balance with [`GET` customer](https://api.shopwaive.com/classic/reference/rest-api-documentation/customer-api.md#get-customer-endpoint) to confirm.

## Delete an entry

> Deletes the entries with this id. This changes real balances in your store.\
> \
> When a deleted entry added or took an amount, and it is not marked redeemed or expired, Shopwaive asks for that amount to be reversed on the balance: only \`remaining\` when it is above 0 and below the amount, else the whole amount. Each entry in the answer says what happened to it. Read the balance with GET customer to confirm.\
> \
> This route takes up to 20 requests a second.<br>

```json
{"openapi":"3.1.0","info":{"title":"Shopwaive API","version":"2026-11"},"tags":[{"name":"Action API","description":"Read, update and delete the entries (actions) that make up a customer's balance."}],"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}}},"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"}}},"schemas":{"DeleteResult":{"type":"object","properties":{"actions":{"type":"array","items":{"anyOf":[{"type":"object","description":"The entry was deleted. When it had an amount, its reversal on the balance was confirmed.","properties":{"status":{"type":"string","const":"success"},"actionid":{"type":["string","number"]}}},{"allOf":[{"$ref":"#/components/schemas/Entry"}],"description":"The entry with a `message`: `action deleted but is not eligible for balance adjustments. If required, update balance with the Customer API` (deleted, balance not changed), or `action is not eligible for deletion` (not deleted)."}]}}}},"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"]}}},"Expires":{"description":"`true` when the amount expires on `expirationdate`, else `false`. Sent and stored as text.","type":["string","boolean"]},"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"}}},"CredentialMissing":{"type":"object","properties":{"status":{"type":"string","const":"failed_credential"},"message":{"type":"string","const":"Send the store's X-Shopwaive-Access-Token. An address key is not a credential; nothing was changed."}}},"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"}}},"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"}}},"RateLimited":{"type":"object","properties":{"error":{"type":"string"}}},"ReversalNotConfirmed":{"description":"An entry was deleted, but its balance reversal could not be confirmed.","type":"object","properties":{"status":{"type":"string","const":"failed"},"reason":{"type":"string","const":"reversal_not_confirmed"},"message":{"type":"string"},"actions":{"description":"What happened to each entry with this id, as in a 200 answer. An entry whose reversal could not be confirmed has `status` `failed` and `reason` `reversal_unconfirmed` (its outcome is not known) or `reversal_refused` (the ledger refused it).","type":"array","items":{"type":"object"}}}},"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."}}},"IdempotencyPending":{"type":"object","properties":{"status":{"type":"string","const":"pending"},"code":{"type":"string","enum":["IDEMPOTENCY_OUTCOME_PENDING","IDEMPOTENCY_STORE_UNAVAILABLE"]},"message":{"type":"string"}}}},"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"}]}}}},"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"}}}}}},"paths":{"/api/action/{actionid}":{"delete":{"tags":["Action API"],"operationId":"deleteAction","summary":"Delete an entry","description":"Deletes the entries with this id. This changes real balances in your store.\n\nWhen a deleted entry added or took an amount, and it is not marked redeemed or expired, Shopwaive asks for that amount to be reversed on the balance: only `remaining` when it is above 0 and below the amount, else the whole amount. Each entry in the answer says what happened to it. Read the balance with GET customer to confirm.\n\nThis route takes up to 20 requests a second.\n","parameters":[{"$ref":"#/components/parameters/Platform"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"What happened to each entry with this id. `actions` is empty when none has it.","headers":{"X-Shopwaive-Request-Id":{"$ref":"#/components/headers/RequestId"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResult"}}}},"201":{"$ref":"#/components/responses/PlatformRefused"},"400":{"$ref":"#/components/responses/IdempotencyKeyMissingOrInvalid"},"401":{"description":"No X-Shopwaive-Access-Token was sent, or the API key was not accepted.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CredentialMissing"},{"$ref":"#/components/schemas/UnknownToken"},{"$ref":"#/components/schemas/KeyRefused"}]}}}},"403":{"$ref":"#/components/responses/KeyMissingScope"},"409":{"$ref":"#/components/responses/IdempotencyBusy"},"422":{"$ref":"#/components/responses/IdempotencyMismatch"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"An entry was deleted, but its balance reversal could not be confirmed. Do not send this request again. Read the customer's balance with GET customer, and contact support@shopwaive.com with the request id. `actions` says what happened to each entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReversalNotConfirmed"}}}},"503":{"description":"Another request is deleting the same entry, the key could not be checked, or the outcome of a request with this Idempotency-Key is not known yet. This answer changed nothing. Retry after the seconds in Retry-After, with the same Idempotency-Key.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/TemporarilyUnavailable"},{"$ref":"#/components/schemas/KeyCheckUnavailable"},{"$ref":"#/components/schemas/IdempotencyPending"}]}}}}}}}}}
```

### Answer

`actions` lists what happened to each entry with this id:

| Item                                                                                                                                      | Meaning                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `{"status": "success", "actionid": "..."}`                                                                                                | Deleted. When it had an amount, its reversal on the balance was confirmed. |
| The entry, with `message` "action deleted but is not eligible for balance adjustments. If required, update balance with the Customer API" | Deleted. The balance did not change.                                       |
| The entry, with `message` "action is not eligible for deletion"                                                                           | Not deleted.                                                               |

{% hint style="info" %}
One id can belong to several entries, for example the entries of one order. Each of them is deleted.
{% endhint %}

| Status                                       | When                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` with `status` `failed_credential`      | No `X-Shopwaive-Access-Token` was sent.                                                                                                                                                                                                                                                                                                                                                         |
| `503` with `status` `failed_temporary`       | Another request is deleting the same entry. Nothing was changed. Retry after `Retry-After`.                                                                                                                                                                                                                                                                                                     |
| `502` with `reason` `reversal_not_confirmed` | An entry was deleted, but its balance reversal was not confirmed. `actions` lists each entry: the one not confirmed has `status` `failed`. Do not send the request again. Read the customer's balance with [`GET` customer](https://api.shopwaive.com/classic/reference/rest-api-documentation/customer-api.md#get-customer-endpoint), and contact <support@shopwaive.com> with the request id. |

This route takes up to 20 requests a second.

## Retry safely

`POST` and `DELETE` 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 is done twice.

| 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 a different entry or different fields.                                       |
| `503`  | `pending`                            | The outcome is not known yet. Read the entry with `GET`, then retry with the same key after `Retry-After`. |
