iRetail PRO store node 1.0.0-m1: loyalty

31 operations

← All documentation · Source: contracts openapi/store-v1.yaml at 8000474.

Operations

GET /v1/loyalty/programs Loyalty programs (spec/LOYALTY.md, Programs).

operationId listLoyaltyPrograms · Permission item.read

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).

Responses

200 OK array of LoyaltyProgram
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error

POST /v1/loyalty/programs Add a loyalty program.

operationId createLoyaltyProgram · Permission loyalty.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`Idempotency-Key`	header	`string`	spec/API.md, Idempotency.

Request body required

application/json LoyaltyProgramWrite

Responses

201 OK LoyaltyProgram
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
409 Error (spec/API.md). Error
422 Error (spec/API.md). Error

PATCH /v1/loyalty/programs/{id} Change a loyalty program; its kind stays.

operationId patchLoyaltyProgram · Permission loyalty.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.
`If-Match`	header	`string`	The version the change is based on.

Request body required

application/json LoyaltyProgramPatch

Responses

200 OK LoyaltyProgram
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
409 Error (spec/API.md). Error
412 Error (spec/API.md). Error
422 Error (spec/API.md). Error

GET /v1/customers Customers, masked; by a name's prefix or a phone's last four digits.

operationId listCustomers · Permission customer.read

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`q`	query	`string`	A name's prefix or the last four digits of a phone.
`limit`	query	`integer`	Page size, 1–200.
`after`	query	`string`	Cursor from the previous page.

Responses

200 OK CustomerPage
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error

POST /v1/customers Enroll a customer (at the hub in a chain, online only).

operationId createCustomer · Permission customer.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`Idempotency-Key`	header	`string`	spec/API.md, Idempotency.

Request body required

application/json CustomerCreate

Responses

201 OK Customer
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
409 Error (spec/API.md). Error
422 Error (spec/API.md). Error
503 Error (spec/API.md). Error

POST /v1/customers/lookup The customer a card number or an E.164 phone finds, exactly; masked.

A POST so that neither the phone nor the card number is ever in a URL, where proxies and access logs keep it (spec/LOYALTY.md, Customers). Exactly one of card and phone; nothing is stored but the answer's presence token, good for 15 minutes for this customer's points and stamps holds (spec/LOYALTY.md, Presence).

operationId lookupCustomer · Permission customer.read

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).

Request body required

application/json CustomerLookup

Responses

200 OK Customer
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
503 Error (spec/API.md). Error

GET /v1/customers/{id} One customer, masked.

operationId getCustomer · Permission customer.read

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.

Responses

200 OK Customer
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
503 Error (spec/API.md). Error

PATCH /v1/customers/{id} Change a customer's record or cards.

operationId patchCustomer · Permission customer.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.
`If-Match`	header	`string`	The version the change is based on.

Request body required

application/json CustomerPatch

Responses

200 OK Customer
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
409 Error (spec/API.md). Error
412 Error (spec/API.md). Error
422 Error (spec/API.md). Error
503 Error (spec/API.md). Error

DELETE /v1/customers/{id} Erase the customer's personal data; the ledgers' totals stay (spec/LOYALTY.md, Customers).

operationId deleteCustomer · Permission customer.delete

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.
`If-Match`	header	`string`	The version the change is based on.

Responses

200 OK Customer
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
412 Error (spec/API.md). Error
503 Error (spec/API.md). Error

GET /v1/customers/{id}/balances The customer's points and stamps at the balance owner.

operationId getCustomerBalances · Permission customer.read

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.

Responses

200 OK CustomerBalances
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
503 Error (spec/API.md). Error

GET /v1/customers/{id}/ledger The customer's ledger entries, newest first.

operationId listCustomerLedger · Permission loyalty.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.
`program_id`	query	`string (uuid)`	One program's.
`limit`	query	`integer`	Page size, 1–200.
`after`	query	`string`	Cursor from the previous page.

Responses

200 OK LedgerPage
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error

POST /v1/customers/{id}/adjustments Correct a customer's points or stamps with a reason; audited.

operationId adjustCustomerBalance · Permission loyalty.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.
`Idempotency-Key`	header	`string`	spec/API.md, Idempotency.

Request body required

application/json BalanceAdjustment

Responses

201 OK LedgerEntry
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
409 Error (spec/API.md). Error
503 Error (spec/API.md). Error

GET /v1/loyalty/holds Balance holds by status (orphaned ones for a person to look at).

operationId listBalanceHolds · Permission loyalty.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`status`	query	`BalanceHoldStatus`	Status.
`limit`	query	`integer`	Page size, 1–200.
`after`	query	`string`	Cursor from the previous page.

Responses

200 OK BalanceHoldPage
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error

POST /v1/loyalty/holds Reserve points, stamps, a gift card amount or a voucher use at the balance owner for 15 minutes.

operationId createBalanceHold · Permission receipt.sell

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`Idempotency-Key`	header	`string`	spec/API.md, Idempotency.

Request body required

application/json BalanceHoldCreate

Responses

201 OK BalanceHold
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
409 Error (spec/API.md). Error
422 Error (spec/API.md). Error
503 Error (spec/API.md). Error

DELETE /v1/loyalty/holds/{id} Release a held hold (a cleared sale) with receipt.sell, or an orphaned one with loyalty.manage alone (spec/LOYALTY.md, Expiry and release).

operationId releaseBalanceHold · Permission receipt.sell

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.

Responses

200 OK BalanceHold
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
409 Error (spec/API.md). Error
503 Error (spec/API.md). Error

GET /v1/vouchers Vouchers and coupons.

operationId listVouchers · Permission item.read

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`active`	query	`boolean`	Active only, or inactive only.
`coupons`	query	`boolean`	Coupons only (max_uses null).
`limit`	query	`integer`	Page size, 1–200.
`after`	query	`string`	Cursor from the previous page.

Responses

200 OK VoucherPage
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error

POST /v1/vouchers Add a voucher or coupon.

operationId createVoucher · Permission voucher.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`Idempotency-Key`	header	`string`	spec/API.md, Idempotency.

Request body required

application/json VoucherCreate

Responses

201 OK Voucher
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
409 Error (spec/API.md). Error
422 Error (spec/API.md). Error

POST /v1/vouchers/generate Make vouchers with codes the node generates.

operationId generateVouchers · Permission voucher.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`Idempotency-Key`	header	`string`	spec/API.md, Idempotency.

Request body required

application/json VouchersGenerate

Responses

201 OK array of Voucher
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
422 Error (spec/API.md). Error

PATCH /v1/vouchers/{id} Change a voucher; its code and rule stay.

operationId patchVoucher · Permission voucher.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.
`If-Match`	header	`string`	The version the change is based on.

Request body required

application/json VoucherPatch

Responses

200 OK Voucher
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
409 Error (spec/API.md). Error
412 Error (spec/API.md). Error
422 Error (spec/API.md). Error

POST /v1/vouchers/lookup A code's voucher and whether it can be used now.

A POST so that a voucher's code, a bearer code for a limited voucher, is never in a URL (spec/LOYALTY.md, Vouchers and coupons). Nothing is stored.

operationId lookupVoucher · Permission receipt.sell

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).

Request body required

application/json VoucherLookup

Responses

200 OK VoucherCheck
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
503 Error (spec/API.md). Error

GET /v1/gift-cards Gift cards, masked.

operationId listGiftCards · Permission gift_card.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`batch_id`	query	`string (uuid)`	The cards one issue or import made.
`status`	query	`"active" \| "blocked"`	Status.
`limit`	query	`integer`	Page size, 1–200.
`after`	query	`string`	Cursor from the previous page.

Responses

200 OK GiftCardPage
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error

POST /v1/gift-cards/balance A card's balance; the number goes in the body, never in a URL.

A card with a PIN shows its balance only with the PIN (null without it; a wrong one is 403 gift_card_pin_wrong and counts toward the lock); 20 lookups a token in a fixed 10-minute window (429 too_many_requests); a number no card has is 404 (spec/LOYALTY.md, Balance).

operationId giftCardBalance · Permission receipt.sell

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).

Request body required

application/json GiftCardBalanceRequest

Responses

200 OK GiftCardBalance
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
409 Error (spec/API.md). Error
429 Error (spec/API.md). Error
503 Error (spec/API.md). Error

GET /v1/gift-cards/{id} One gift card, masked, with its balance.

operationId getGiftCard · Permission gift_card.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.

Responses

200 OK GiftCard
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
503 Error (spec/API.md). Error

PATCH /v1/gift-cards/{id} Block or unblock a gift card; audited.

operationId patchGiftCard · Permission gift_card.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.
`If-Match`	header	`string`	The version the change is based on.

Request body required

application/json GiftCardPatch

Responses

200 OK GiftCard
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
409 Error (spec/API.md). Error
412 Error (spec/API.md). Error

POST /v1/gift-cards/issue Make cards with random 16-digit numbers; the numbers and PINs are shown in this answer only.

spec/LOYALTY.md, Gift card numbers. No Idempotency-Key: nothing of the answer is kept, so a lost answer leaves cards to block by their batch_id.

operationId issueGiftCards · Permission gift_card.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).

Request body required

application/json GiftCardIssue

Responses

201 OK GiftCardsIssued
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
409 Error (spec/API.md). Error

POST /v1/gift-cards/import Import cards a supplier printed by number; each number is hashed and dropped.

spec/LOYALTY.md, Gift card numbers. The body is never logged; an Idempotency-Key keeps a hash of it, never the body.

operationId importGiftCards · Permission gift_card.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`Idempotency-Key`	header	`string`	spec/API.md, Idempotency.

Request body required

application/json GiftCardImport

Responses

201 OK GiftCardsImported
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
409 Error (spec/API.md). Error

PUT /v1/gift-cards/{id}/pin Set or remove a card's PIN, kept as an Argon2id hash; audited, never the PIN.

operationId setGiftCardPin · Permission gift_card.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.
`If-Match`	header	`string`	The version the change is based on.

Request body required

application/json GiftCardPinPut

Responses

200 OK GiftCard
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
409 Error (spec/API.md). Error
412 Error (spec/API.md). Error

GET /v1/gift-cards/{id}/ledger A gift card's ledger entries, newest first.

operationId listGiftCardLedger · Permission gift_card.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.
`limit`	query	`integer`	Page size, 1–200.
`after`	query	`string`	Cursor from the previous page.

Responses

200 OK LedgerPage
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error

GET /v1/partners Partners and their codes.

operationId listPartners · Permission item.read

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).

Responses

200 OK array of Partner
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error

POST /v1/partners Add a partner.

operationId createPartner · Permission partner.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`Idempotency-Key`	header	`string`	spec/API.md, Idempotency.

Request body required

application/json PartnerWrite

Responses

201 OK Partner
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
409 Error (spec/API.md). Error
422 Error (spec/API.md). Error

PATCH /v1/partners/{id} Change a partner.

operationId patchPartner · Permission partner.manage

Parameters

Name	In	Type	Description
`IRetail-App`	header	`string`	Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking).
`id` required	path	`string (uuid)`	Id.
`If-Match`	header	`string`	The version the change is based on.

Request body required

application/json PartnerPatch

Responses

200 OK Partner
400 Error (spec/API.md). Error
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
409 Error (spec/API.md). Error
412 Error (spec/API.md). Error
422 Error (spec/API.md). Error

Schemas

`Error` object

Every error response.

`error` required	`string`	Stable code, see spec/API.md.
`message` required	`string`	English text for logs.
`details`	`object`

`LocalizedText` map of string

Text by language code; the organization's default language must be present.

`PromotionRule` object | object

spec/PROMOTIONS.md.

`LoyaltyKind` "discount" | "bonus" | "stamps"

discount · bonus · stamps

`LoyaltyProgram` object

spec/LOYALTY.md, Programs; hub-owned in a chain.

`id` required	`string (uuid)`
`name` required	`LocalizedText`
`kind` required	`LoyaltyKind`
`active` required	`boolean`
`rate_ppm` required	`integer \| null`	discount: the card's percent.
`earn` required	`array of object`	bonus: earn rates by group; a group_id of null for every group not listed.
`point_values` required	`array of object`	bonus: one point's value in a store's currency; store_id null for the others.
`max_spend_ppm` required	`integer \| null`	bonus: the largest share points may pay.
`stamps_per_reward` required	`integer \| null`	stamps: every Nth item free.
`item_ids` required	`array of string (uuid)`
`group_ids` required	`array of string (uuid)`
`excluded_group_ids` required	`array of string (uuid)`	discount and bonus: groups the card never touches.
`version` required	`integer (int64)`

`LoyaltyProgramWrite` object

`name` required	`LocalizedText`
`kind` required	`LoyaltyKind`
`active`	`boolean`
`rate_ppm`	`integer \| null`	discount: the card's percent.
`earn`	`array of object`	bonus: earn rates by group; a group_id of null for every group not listed.
`point_values`	`array of object`	bonus: one point's value in a store's currency; store_id null for the others.
`max_spend_ppm`	`integer \| null`	bonus: the largest share points may pay.
`stamps_per_reward`	`integer \| null`	stamps: every Nth item free.
`item_ids`	`array of string (uuid)`
`group_ids`	`array of string (uuid)`
`excluded_group_ids`	`array of string (uuid)`	discount and bonus: groups the card never touches.

`LoyaltyProgramPatch` object

`name`	`LocalizedText`
`active`	`boolean`
`rate_ppm`	`integer \| null`	discount: the card's percent.
`earn`	`array of object`	bonus: earn rates by group; a group_id of null for every group not listed.
`point_values`	`array of object`	bonus: one point's value in a store's currency; store_id null for the others.
`max_spend_ppm`	`integer \| null`	bonus: the largest share points may pay.
`stamps_per_reward`	`integer \| null`	stamps: every Nth item free.
`item_ids`	`array of string (uuid)`
`group_ids`	`array of string (uuid)`
`excluded_group_ids`	`array of string (uuid)`	discount and bonus: groups the card never touches.

`CustomerCard` object

`program_id` required	`string (uuid)`
`number_masked` required	`string`

`CustomerCardInput` object

`program_id` required	`string (uuid)`
`number` required	`string`

`CustomerConsent` object

`at` required	`string (date-time)`
`source` required	`"register" \| "back_office" \| "customer_app" \| "import"`
`terms_version` required	`string`

`CustomerMarketing` object

`allowed` required	`boolean`
`at` required	`string (date-time) \| null`

`Customer` object

A customer as every answer shows one: phone, e-mail and card numbers masked (spec/LOYALTY.md, Customers).

`id` required	`string (uuid)`
`name` required	`string \| null`
`phone_masked` required	`string \| null`
`email_masked` required	`string \| null`
`cards` required	`array of CustomerCard`
`consent` required	`CustomerConsent`
`marketing` required	`CustomerMarketing`
`deleted_at` required	`string (date-time) \| null`
`created_at` required	`string (date-time)`
`version` required	`integer (int64)`
`presence_token`	`string`	Only in the answer of POST /v1/customers/lookup; shown once (spec/LOYALTY.md, Presence).
`presence_expires_at`	`string (date-time)`	Only with presence_token.

`CustomerCreate` object

`name`	`string \| null`
`phone`	`string \| null`	E.164; written, never read back.
`email`	`string (email) \| null`	Written, never read back.
`cards`	`array of CustomerCardInput`
`marketing`	`CustomerMarketing`
`consent` required	`CustomerConsent`

`CustomerPatch` object

Fields given replace; cards, when given, replace all.

`name`	`string \| null`
`phone`	`string \| null`	E.164; written, never read back.
`email`	`string (email) \| null`	Written, never read back.
`cards`	`array of CustomerCardInput`
`marketing`	`CustomerMarketing`

`CustomerPage` object

`items` required	`array of Customer`
`next` required	`string \| null`

`CustomerBalances` object

What the balance owner holds for the customer (spec/LOYALTY.md, Balances and their owner).

`customer_id` required	`string (uuid)`
`points` required	`array of object`
`stamps` required	`array of object`

`AccountKind` "points" | "stamps" | "gift_card" | "voucher"

points · stamps · gift_card · voucher

`LedgerEntry` object

One change of a balance (spec/LOYALTY.md).

`id` required	`string (uuid)`
`account_kind` required	`AccountKind`
`account_id` required	`string (uuid)`
`program_id` required	`string (uuid) \| null`
`kind` required	`"points_earned" \| "points_spent" \| "points_earned_reversed" \| "points_spent_returned" \| "stamps_earned" \| "stamps_redeemed" \| "stamps_reversed" \| "gift_card_loaded" \| "gift_card_spent" \| "gift_card_refunded" \| "gift_card_unloaded" \| "voucher_used" \| "voucher_returned" \| "adjustment"`
`amount` required	`integer (int64)`
`receipt_id` required	`string (uuid) \| null`
`hold_id` required	`string (uuid) \| null`
`store_id` required	`string (uuid)`
`reason` required	`string \| null`
`at` required	`string (date-time)`

`LedgerPage` object

`items` required	`array of LedgerEntry`
`next` required	`string \| null`

`BalanceAdjustment` object

A person's correction of a customer's points or stamps (not 0).

`program_id` required	`string (uuid)`
`amount` required	`integer (int64)`
`reason` required	`string`

`BalanceHoldStatus` "held" | "committed" | "settled" | "expired" | "released" | "orphaned"

held · committed · settled · expired · released · orphaned

`CustomerLookup` object

Exactly one of card and phone (400 bad_request otherwise); never logged or kept.

`card`	`string`	A loyalty card number.
`phone`	`string`	An E.164 phone number.

`VoucherLookup` object

code required string The code as typed or scanned; never logged or kept.

`BalanceHoldCreate` object

points and stamps: customer_id and program_id, and card_number, card_token or presence_token (422 presence_required otherwise; spec/LOYALTY.md, Presence); gift_card: the number; voucher: the code.

`account_kind` required	`AccountKind`
`customer_id`	`string (uuid) \| null`
`program_id`	`string (uuid) \| null`
`gift_card_number`	`string \| null`	As typed or scanned; normalized and Luhn-checked before any lookup (spec/LOYALTY.md, Gift card numbers); never logged or kept.
`gift_card_pin`	`string \| null`	The card's PIN, when it has one; never logged or kept.
`voucher_code`	`string \| null`
`card_number`	`string \| null`	points and stamps: the customer's loyalty card scanned in this sale; never logged or kept.
`presence_token`	`string \| null`	points and stamps: the token POST /v1/customers/lookup gave for this customer, within 15 minutes and not spent (spec/LOYALTY.md, Presence).
`card_token`	`string \| null`	points and stamps: the card token the customer app showed, as scanned (spec/PUBLIC_API.md, The card); never logged or kept.
`amount` required	`integer (int64)`	Points, stamps, minor units of the card's currency, or uses.

`BalanceHold` object

spec/LOYALTY.md, Balances and their owner.

`id` required	`string (uuid)`
`account_kind` required	`AccountKind`
`account_id` required	`string (uuid)`
`program_id` required	`string (uuid) \| null`
`amount` required	`integer (int64)`
`status` required	`BalanceHoldStatus`
`expires_at` required	`string (date-time) \| null`
`store_id` required	`string (uuid)`
`receipt_id` required	`string (uuid) \| null`
`created_at` required	`string (date-time)`
`committed_at` required	`string (date-time) \| null`

`BalanceHoldPage` object

`items` required	`array of BalanceHold`
`next` required	`string \| null`

`VoucherRule` @PromotionRule | object

PROMOTIONS.md's rules on a line's current net, or an amount off the receipt (spec/LOYALTY.md).

`Voucher` object

spec/LOYALTY.md, Vouchers and coupons; hub-owned in a chain.

`id` required	`string (uuid)`
`code` required	`string`
`name` required	`LocalizedText \| null`
`rule` required	`VoucherRule`
`item_ids` required	`array of string (uuid)`
`group_ids` required	`array of string (uuid)`
`min_spend_minor` required	`integer (int64)`
`starts_at` required	`string (date-time) \| null`
`ends_at` required	`string (date-time) \| null`
`max_uses` required	`integer \| null`	null: a coupon, used any number of times.
`customer_id` required	`string (uuid) \| null`
`active` required	`boolean`
`uses` required	`integer (int64)`
`version` required	`integer (int64)`

`VoucherCreate` object

`code`	`string \| null`	null: the node makes one.
`name`	`LocalizedText \| null`
`rule` required	`VoucherRule`
`item_ids`	`array of string (uuid)`
`group_ids`	`array of string (uuid)`
`min_spend_minor`	`integer (int64)`
`starts_at`	`string (date-time) \| null`
`ends_at`	`string (date-time) \| null`
`max_uses`	`integer \| null`	null: a coupon, used any number of times.
`customer_id`	`string (uuid) \| null`
`active`	`boolean`

`VoucherPatch` object

`name`	`LocalizedText \| null`
`item_ids`	`array of string (uuid)`
`group_ids`	`array of string (uuid)`
`min_spend_minor`	`integer (int64)`
`starts_at`	`string (date-time) \| null`
`ends_at`	`string (date-time) \| null`
`max_uses`	`integer \| null`	null: a coupon, used any number of times.
`customer_id`	`string (uuid) \| null`
`active`	`boolean`

`VouchersGenerate` object

count vouchers like the given one, each with a code the node makes.

`count` required	`integer`
`voucher` required	`VoucherCreate`

`VoucherPage` object

`items` required	`array of Voucher`
`next` required	`string \| null`

`VoucherCheck` object

`voucher` required	`Voucher`
`remaining_uses` required	`integer (int64) \| null`
`usable` required	`boolean`
`reason` required	`"inactive" \| "not_started" \| "ended" \| "used_up" \| "other_customer" \| null`

`GiftCard` object

spec/LOYALTY.md, Gift cards. Only the number's mask is here; the owner finds a card by the number's keyed hash, which no answer carries. The balance is the owner's (null in a replicated copy).

`id` required	`string (uuid)`
`number_masked` required	`string`
`currency` required	`string`
`status` required	`"active" \| "blocked"`
`has_pin` required	`boolean`
`batch_id` required	`string (uuid)`	The issue or import that made the card.
`balance_minor` required	`integer (int64) \| null`
`available_minor` required	`integer (int64) \| null`
`created_at` required	`string (date-time)`
`version` required	`integer (int64)`

`GiftCardPatch` object

status required "active" | "blocked"

`GiftCardPage` object

`items` required	`array of GiftCard`
`next` required	`string \| null`

`GiftCardBalanceRequest` object

`number` required	`string`	As typed or scanned; spaces and hyphens go, and 12 to 19 digits with a Luhn check digit must remain (spec/LOYALTY.md, Gift card numbers). Never logged or kept.
`pin`	`string \| null`	The card's PIN, when it has one; without it a card with a PIN answers no balance. Never logged or kept.

`GiftCardBalance` object

`gift_card_id` required	`string (uuid)`
`number_masked` required	`string`
`currency` required	`string`
`status` required	`"active" \| "blocked"`
`has_pin` required	`boolean`
`balance_minor` required	`integer (int64) \| null`	Null for a card with a PIN asked without it (spec/LOYALTY.md, Balance).
`available_minor` required	`integer (int64) \| null`	Null with balance_minor.

`Partner` object

spec/LOYALTY.md, Partner codes; hub-owned in a chain.

`id` required	`string (uuid)`
`name` required	`string`
`codes` required	`array of string`
`commission_ppm` required	`integer`
`item_ids` required	`array of string (uuid)`
`group_ids` required	`array of string (uuid)`
`starts_at` required	`string (date-time) \| null`
`ends_at` required	`string (date-time) \| null`
`active` required	`boolean`
`version` required	`integer (int64)`

`PartnerWrite` object

`name` required	`string`
`codes` required	`array of string`
`commission_ppm` required	`integer`
`item_ids`	`array of string (uuid)`
`group_ids`	`array of string (uuid)`
`starts_at`	`string (date-time) \| null`
`ends_at`	`string (date-time) \| null`
`active`	`boolean`

`PartnerPatch` object

`name`	`string`
`codes`	`array of string`
`commission_ppm`	`integer`
`item_ids`	`array of string (uuid)`
`group_ids`	`array of string (uuid)`
`starts_at`	`string (date-time) \| null`
`ends_at`	`string (date-time) \| null`
`active`	`boolean`

`GiftCardIssue` object

`count` required	`integer`
`currency` required	`string`
`with_pins`	`boolean`	Give each card a random 4-digit PIN.

`GiftCardsIssued` object

The only answer that holds numbers and PINs in clear, for printing; nothing of it is kept or logged.

`batch_id` required	`string (uuid)`
`cards` required	`array of object`

`GiftCardImport` object

`currency` required	`string`
`cards` required	`array of object`

`GiftCardsImported` object

`batch_id` required	`string (uuid)`
`imported` required	`integer`
`skipped` required	`integer`	Numbers that were already a card's.
`cards` required	`array of object`

`GiftCardPinPut` object

pin required string | null The new PIN; null removes it. Never logged or kept in clear.