iRetail PRO
English Получить ключ
Меню

iRetail PRO store node 1.0.0-m1: loyalty

31 операция

← Вся документация · Источник: контракты, openapi/store-v1.yaml на коммите 8000474.

Справочники на английском — на языке контрактов, из которых они созданы.

← iRetail PRO store node 1.0.0-m1

Операции

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

operationId listLoyaltyPrograms · Право item.read

Параметры

Имя Где Тип Описание
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).

Ответы

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

operationId createLoyaltyProgram · Право loyalty.manage

Параметры

Имя Где Тип Описание
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.

Тело запроса обязательный

Ответы

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

operationId patchLoyaltyProgram · Право loyalty.manage

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.
If-Match header string The version the change is based on.

Тело запроса обязательный

Ответы

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

operationId listCustomers · Право customer.read

Параметры

Имя Где Тип Описание
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.

Ответы

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

operationId createCustomer · Право customer.manage

Параметры

Имя Где Тип Описание
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.

Тело запроса обязательный

Ответы

  • 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 · Право customer.read

Параметры

Имя Где Тип Описание
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).

Тело запроса обязательный

Ответы

  • 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 · Право customer.read

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.

Ответы

  • 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 · Право customer.manage

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.
If-Match header string The version the change is based on.

Тело запроса обязательный

Ответы

  • 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 · Право customer.delete

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.
If-Match header string The version the change is based on.

Ответы

  • 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 · Право customer.read

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.

Ответы

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

operationId listCustomerLedger · Право loyalty.manage

Параметры

Имя Где Тип Описание
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 обязательный 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.

Ответы

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

operationId adjustCustomerBalance · Право loyalty.manage

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.
Idempotency-Key header string spec/API.md, Idempotency.

Тело запроса обязательный

Ответы

  • 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 · Право loyalty.manage

Параметры

Имя Где Тип Описание
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.

Ответы

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

operationId createBalanceHold · Право receipt.sell

Параметры

Имя Где Тип Описание
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.

Тело запроса обязательный

Ответы

  • 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 · Право receipt.sell

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.

Ответы

GET /v1/vouchers Vouchers and coupons.

operationId listVouchers · Право item.read

Параметры

Имя Где Тип Описание
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.

Ответы

POST /v1/vouchers Add a voucher or coupon.

operationId createVoucher · Право voucher.manage

Параметры

Имя Где Тип Описание
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.

Тело запроса обязательный

Ответы

  • 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 · Право voucher.manage

Параметры

Имя Где Тип Описание
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.

Тело запроса обязательный

Ответы

  • 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 · Право voucher.manage

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.
If-Match header string The version the change is based on.

Тело запроса обязательный

Ответы

  • 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 · Право receipt.sell

Параметры

Имя Где Тип Описание
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).

Тело запроса обязательный

Ответы

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

operationId listGiftCards · Право gift_card.manage

Параметры

Имя Где Тип Описание
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.

Ответы

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 · Право receipt.sell

Параметры

Имя Где Тип Описание
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).

Тело запроса обязательный

Ответы

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

operationId getGiftCard · Право gift_card.manage

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.

Ответы

  • 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 · Право gift_card.manage

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.
If-Match header string The version the change is based on.

Тело запроса обязательный

Ответы

  • 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 · Право gift_card.manage

Параметры

Имя Где Тип Описание
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).

Тело запроса обязательный

Ответы

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 · Право gift_card.manage

Параметры

Имя Где Тип Описание
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.

Тело запроса обязательный

Ответы

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

operationId setGiftCardPin · Право gift_card.manage

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.
If-Match header string The version the change is based on.

Тело запроса обязательный

Ответы

  • 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 · Право gift_card.manage

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.
limit query integer Page size, 1–200.
after query string Cursor from the previous page.

Ответы

GET /v1/partners Partners and their codes.

operationId listPartners · Право item.read

Параметры

Имя Где Тип Описание
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).

Ответы

  • 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 · Право partner.manage

Параметры

Имя Где Тип Описание
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.

Тело запроса обязательный

Ответы

  • 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 · Право partner.manage

Параметры

Имя Где Тип Описание
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 обязательный path string (uuid) Id.
If-Match header string The version the change is based on.

Тело запроса обязательный

Ответы

  • 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

Схемы

Error object

Every error response.

error обязательный string Stable code, see spec/API.md.
message обязательный 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 обязательный string (uuid)
name обязательный LocalizedText
kind обязательный 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.
version обязательный integer (int64)

LoyaltyProgramWrite object

name обязательный LocalizedText
kind обязательный 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 обязательный string (uuid)
number_masked обязательный string

CustomerCardInput object

program_id обязательный string (uuid)
number обязательный string

CustomerConsent object

at обязательный string (date-time)
source обязательный "register" | "back_office" | "customer_app" | "import"
terms_version обязательный string

CustomerMarketing object

allowed обязательный boolean
at обязательный 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 обязательный string (uuid)
name обязательный string | null
phone_masked обязательный string | null
email_masked обязательный string | null
cards обязательный array of CustomerCard
consent обязательный CustomerConsent
marketing обязательный CustomerMarketing
deleted_at обязательный string (date-time) | null
created_at обязательный string (date-time)
version обязательный 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 обязательный 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 обязательный array of Customer
next обязательный string | null

CustomerBalances object

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

customer_id обязательный string (uuid)
points обязательный array of object
stamps обязательный 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 обязательный string (uuid)
account_kind обязательный AccountKind
account_id обязательный string (uuid)
program_id обязательный string (uuid) | null
kind обязательный "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 обязательный integer (int64)
receipt_id обязательный string (uuid) | null
hold_id обязательный string (uuid) | null
store_id обязательный string (uuid)
reason обязательный string | null
at обязательный string (date-time)

LedgerPage object

items обязательный array of LedgerEntry
next обязательный string | null

BalanceAdjustment object

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

program_id обязательный string (uuid)
amount обязательный integer (int64)
reason обязательный 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 обязательный 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 обязательный 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 обязательный integer (int64) Points, stamps, minor units of the card's currency, or uses.

BalanceHold object

spec/LOYALTY.md, Balances and their owner.

id обязательный string (uuid)
account_kind обязательный AccountKind
account_id обязательный string (uuid)
program_id обязательный string (uuid) | null
amount обязательный integer (int64)
status обязательный BalanceHoldStatus
expires_at обязательный string (date-time) | null
store_id обязательный string (uuid)
receipt_id обязательный string (uuid) | null
created_at обязательный string (date-time)
committed_at обязательный string (date-time) | null

BalanceHoldPage object

items обязательный array of BalanceHold
next обязательный 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 обязательный string (uuid)
code обязательный string
name обязательный LocalizedText | null
rule обязательный 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
uses обязательный integer (int64)
version обязательный integer (int64)

VoucherCreate object

code string | null null: the node makes one.
name LocalizedText | null
rule обязательный 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 обязательный integer
voucher обязательный VoucherCreate

VoucherPage object

items обязательный array of Voucher
next обязательный string | null

VoucherCheck object

voucher обязательный Voucher
remaining_uses обязательный integer (int64) | null
usable обязательный boolean
reason обязательный "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 обязательный string (uuid)
number_masked обязательный string
currency обязательный string
status обязательный "active" | "blocked"
has_pin обязательный boolean
batch_id обязательный string (uuid) The issue or import that made the card.
balance_minor обязательный integer (int64) | null
available_minor обязательный integer (int64) | null
created_at обязательный string (date-time)
version обязательный integer (int64)

GiftCardPatch object

status обязательный "active" | "blocked"

GiftCardPage object

items обязательный array of GiftCard
next обязательный string | null

GiftCardBalanceRequest object

number обязательный 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 обязательный string (uuid)
number_masked обязательный string
currency обязательный string
status обязательный "active" | "blocked"
has_pin обязательный boolean
balance_minor обязательный integer (int64) | null Null for a card with a PIN asked without it (spec/LOYALTY.md, Balance).
available_minor обязательный integer (int64) | null Null with balance_minor.

Partner object

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

id обязательный string (uuid)
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
version обязательный integer (int64)

PartnerWrite 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

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 обязательный integer
currency обязательный 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 обязательный string (uuid)
cards обязательный array of object

GiftCardImport object

currency обязательный string
cards обязательный array of object

GiftCardsImported object

batch_id обязательный string (uuid)
imported обязательный integer
skipped обязательный integer Numbers that were already a card's.
cards обязательный array of object

GiftCardPinPut object

pin обязательный string | null The new PIN; null removes it. Never logged or kept in clear.