iRetail PRO store node 1.0.0-m1: receipts
5 operations
← All documentation · Source: contracts openapi/store-v1.yaml at 8000474.
← iRetail PRO store node 1.0.0-m1
Operations
POST
/v1/receipts/calculate
Compute receipt amounts without storing anything (spec/RECEIPT_MATH.md).
Any principal's token (an employee's, a device's or an integration's), no permission; a body of at most 256 KiB (413 payload_too_large) within the math's bounds (spec/RECEIPT_MATH.md, Bounds; 422 amount_too_large). It took no token before 1.0 (spec/API.md, Calculating a receipt).
operationId
calculateReceipt
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/jsonCalculateRequest
Responses
-
200OKCalculateResult -
400Error (spec/API.md).Error -
401Error (spec/API.md).Error -
413Error (spec/API.md).Error -
422Error (spec/API.md).Error
GET
/v1/receipts
Receipts.
operationId
listReceipts · Permission receipt.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). |
shift_id
|
query | string (uuid) |
Shift. |
limit
|
query | integer |
Page size, 1–200. |
after
|
query | string |
Cursor from the previous page. |
Responses
-
200OKReceiptPage -
401Error (spec/API.md).Error -
403Error (spec/API.md).Error
POST
/v1/receipts
Sale (receipt.sell), refund (receipt.refund, receipt.refund.any_shift) or void (receipt.void).
A refund pays back to the sale's tenders, each up to what it paid less earlier refunds; another tender or more needs refund.tender_override (spec/API.md, Payments). What else a receipt needs by its kind and lines is spec/RBAC.md, Permissions by request (data/request-permissions.json).
operationId
createReceipt · 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. |
Approval-Token
|
header | string |
One-time approval from POST /v1/approvals for this operation's permission. |
dry_run
|
query | boolean |
Check and compute the receipt without keeping anything (spec/API.md, "Dry runs"): 200 with the receipt as it would be; payments are not compared with what is due; an approval token is not used up. |
Request body required
application/jsonReceiptCreate
Responses
GET
/v1/receipts/{id}
One receipt.
operationId
getReceipt · Permission receipt.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
POST
/v1/receipts/{id}/send
Send a receipt to the customer by e-mail or SMS (spec/API.md, "Electronic receipts").
receipt.read, and either the caller's workplace rang the sale less than 30 minutes ago or the caller holds receipt.resend (403 forbidden otherwise). Five sends a receipt; per store 100 SMS and 300 e-mails in a fixed UTC hour (429 too_many_sends, details limit and retry_after).
operationId
sendReceipt · Permission receipt.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. |
Request body required
application/jsonReceiptSend
Responses
Schemas
Error object
Every error response.
error required
|
string |
Stable code, see spec/API.md. |
message required
|
string |
English text for logs. |
details
|
object |
ReceiptFiscal object
The fiscal document a back end gave the receipt (spec/FISCAL.md, What the node keeps).
kind required
|
"device" | "signer" | "software" | "service" |
|
driver required
|
string |
|
device_serial required
|
string | null |
|
registration_number required
|
string | null |
|
shift_number required
|
integer (int64) |
|
document_number required
|
integer (int64) |
|
sign required
|
string |
|
qr required
|
string | null |
|
at required
|
string (date-time) |
|
extra required
|
map of string |
Discount object | object
As in spec/RECEIPT_MATH.md.
ReceiptLineInput object
item_id required
|
string (uuid) |
|
quantity_milli required
|
integer (int64) |
At most 10^12 (spec/RECEIPT_MATH.md, Bounds; 422 amount_too_large). |
unit_price_minor
|
integer (int64) |
The price before options (spec/FOOD_SERVICE.md); only with receipt.price.override, otherwise the store price. On a line paying a check line, the check line's price less its options' deltas, with no override (spec/RESTAURANT.md, Split and close). With its options' deltas at most 10^12 (spec/RECEIPT_MATH.md, Bounds). |
discounts
|
array of Discount |
At most 16, an amount at most 10^12 (spec/RECEIPT_MATH.md, Bounds). |
hold_id
|
string (uuid) | null |
|
original_line_no
|
integer |
Refund: the line of the original receipt. |
modifiers
|
array of string |
Sale: option ids of the item's modifier groups, in the chosen order (spec/FOOD_SERVICE.md). |
serials
|
array of string |
A serial-tracked item's serial per unit, as read (spec/VARIANTS.md). |
lot
|
string | null |
Sale: the lot a GS1 code named; its batches go first (spec/BARCODES.md, GS1 codes). |
expiry
|
string (date) | null |
Sale: the expiry date a GS1 code carried; a date before the business date is refused as expired unless approved (expired.sell). |
marking_code
|
string | null |
The marking code a GS1 code carried, as scanned (spec/BARCODES.md, GS1 codes). |
seller_id
|
string (uuid) | null |
Sale: the employee who sold the line and earns its bonus (spec/REPORTS.md, Employee bonuses); the cashier when absent. |
batch_price
|
boolean |
Sale: the line's unit_price_minor is a batch price from the price split (spec/PRICING.md, Batch prices). |
gift_card_id
|
string (uuid) | null |
Sale of a gift_card item: the card loaded, found by its number first (POST /v1/gift-cards/balance; spec/LOYALTY.md, Gift cards). |
check_line_no
|
integer | null |
Sale with check: the check line this line pays, carried as the check has it, its unit_price_minor before options (spec/RESTAURANT.md, Split and close). |
preorder_line_no
|
integer | null |
Sale with preorder: the preorder line this line hands over (spec/PREORDERS.md, Handing it over). |
PaymentInput object
tender required
|
"cash" | "card" | "ebt_snap" | "ebt_cash" | "gift_card" | "online" | "other" |
online is a preorder's payment captured at hand-over (spec/PAYMENTS_ONLINE.md), read as other by an app before 1.1. |
amount_minor required
|
integer (int64) |
At most 10^15 (spec/API.md, Payments; 422 amount_too_large). |
provider
|
string | null |
|
provider_ref
|
string | null |
|
card_brand
|
string | null |
|
card_last4
|
string | null |
|
authorization_code
|
string | null |
|
hold_id
|
string (uuid) | null |
Tender gift_card: the balance hold for the amount, taken with the card's number and PIN; the node fills card_last4 with the card's last four digits (spec/LOYALTY.md, Gift cards). |
OfflineInfo object
Present when a register replays a receipt it closed offline.
created_at required
|
string (date-time) |
|
register_number required
|
string |
The register's own number for the receipt. |
ReceiptCreate object
sale: lines and payments; refund: original_receipt_id, lines with original_line_no, payments returned; void: original_receipt_id only.
kind required
|
"sale" | "refund" | "void" |
|
shift_id required
|
string (uuid) |
|
original_receipt_id
|
string (uuid) | null |
|
lines
|
array of ReceiptLineInput |
At most 1 000 (spec/RECEIPT_MATH.md, Bounds; 422 amount_too_large). |
receipt_discounts
|
array of Discount |
At most 16 (spec/RECEIPT_MATH.md, Bounds). |
payments
|
array of PaymentInput |
At most 20 (spec/API.md, Payments; 422 amount_too_large). |
offline
|
OfflineInfo | null |
|
order_type
|
"dine_in" | "take_out" | "delivery" | null |
How a food-service order leaves; null for retail (spec/FOOD_SERVICE.md). |
tip_minor
|
integer (int64) |
Sale: added to what the payments cover; not part of the total, untaxed. At most 10^15 (spec/API.md, Payments). |
order_label
|
string | null |
Sale: a name or table number for the kitchen display (spec/FOOD_SERVICE.md). |
purchaser
|
PsePurchaser | null |
Sale with a PSE line: the purchaser from the scanned ID (spec/PHARMACY.md); never returned. |
fiscal
|
ReceiptFiscal | null |
The fiscal document the register's back end gave the receipt before it was recorded (spec/FISCAL.md, The sale). |
customer_id
|
string (uuid) | null |
Sale: the customer found online (spec/LOYALTY.md, The sale). |
card_number
|
string | null |
Sale: a loyalty card as scanned, resolved by the node (offline too); never returned. |
points
|
ReceiptPointsInput | null |
Sale: points spent on a bonus card, with their hold. |
stamp_holds
|
array of ReceiptStampHold |
Sale: the holds for stamps rewards take from the cards (spec/LOYALTY.md, Stamps). |
gift_card_holds
|
array of ReceiptGiftCardHold |
Refund and void: for each gift card line taken back, the hold that unloads its amount from the card, taken with the card's number and PIN (spec/LOYALTY.md, Selling, spending, refunds). A gift card line refunded or voided without one is 422 gift_card_hold_required. |
voucher
|
ReceiptVoucherInput | null |
Sale: one voucher or coupon, with its hold when it is limited. |
partner_code
|
string | null |
Sale: a partner's code (spec/LOYALTY.md, Partner codes). |
check
|
ReceiptCheckInput | null |
Sale: the restaurant check whose lines it pays; every line then names its check_line_no (spec/RESTAURANT.md, Split and close). |
preorder
|
string (uuid) | null |
Sale: the preorder it hands over; its lines name their preorder_line_no (spec/PREORDERS.md, Handing it over). |
service_charges
|
array of ReceiptServiceChargeInput |
Sale: every store service charge it carries, each automatic, added or removed; a charge whose conditions hold left out is 422 invalid_service_charge, and a receipt of a check carries the check's (spec/RECEIPT_MATH.md, Service charges). |
ReceiptLineBatch object
batch_id required
|
string (uuid) |
|
quantity_milli required
|
integer (int64) |
|
item_id
|
string (uuid) |
A kit line's component the batch belongs to (spec/STOCK.md, Kits). |
ReceiptLine object
line_no required
|
integer |
|
item_id required
|
string (uuid) |
|
name required
|
string |
The item name in the receipt language at the time of sale. |
quantity_milli required
|
integer (int64) |
|
base_unit required
|
"each" | "kg" | "lb" | "l" | "us_gal" | "m" | "ft" |
|
unit_price_minor required
|
integer (int64) |
|
gross required
|
integer (int64) |
|
line_discount required
|
integer (int64) |
|
receipt_discount required
|
integer (int64) |
|
net required
|
integer (int64) |
|
tax required
|
integer (int64) |
|
deposit required
|
integer (int64) |
The container deposit (spec/TAX.md); 0 without one. |
snap required
|
integer (int64) |
What SNAP paid of the line (spec/TAX.md, "SNAP exemption"); 0 without SNAP. |
batches required
|
array of ReceiptLineBatch |
|
promotion_id required
|
string (uuid) | null |
The promotion that took its discount off the line (spec/PROMOTIONS.md). |
modifiers required
|
array of object |
|
serials
|
array of string |
The line's serials, normalized (spec/VARIANTS.md). |
lot
|
string | null |
Sale: the lot a GS1 code named; its batches go first (spec/BARCODES.md, GS1 codes). |
marking_code
|
string | null |
The marking code a GS1 code carried, as scanned (spec/BARCODES.md, GS1 codes). |
seller_id required
|
string (uuid) | null |
Sale: the employee who sold the line and earns its bonus (spec/REPORTS.md, Employee bonuses); the cashier when absent. |
stamp_discount required
|
integer (int64) |
The loyalty steps' parts of the line's discounts (spec/LOYALTY.md, The order of discounts). |
card_discount required
|
integer (int64) |
|
voucher_discount required
|
integer (int64) |
The voucher's line rule and its share of an amount rule. |
points_spent required
|
integer (int64) |
The points the line took of those spent; 0 without. |
points_earned required
|
integer (int64) |
|
bonus_minor required
|
integer (int64) |
The employee bonus fixed at the sale (spec/REPORTS.md, Employee bonuses). |
bonus_employee_id required
|
string (uuid) | null |
|
bonus_rule_id required
|
string (uuid) | null |
|
commission_minor required
|
integer (int64) |
The line's share of the partner's commission. |
gift_card_number_masked
|
string | null |
A gift card line's card, masked. |
check_line_no required
|
integer | null |
The restaurant check's line this line paid (spec/RESTAURANT.md); null for a sale without a check. |
preorder_line_no
|
integer | null |
The preorder's line this line handed over (spec/PREORDERS.md); null otherwise. |
service_charges required
|
array of ServiceChargeShare |
The line's share of each service charge the receipt applies, with the tax on that share (not in tax); a refund line's, what it took back; empty without (spec/RECEIPT_MATH.md, Service charges). |
ReceiptTax object
code required
|
string |
|
base required
|
integer (int64) |
|
amount required
|
integer (int64) |
Payment object
id required
|
string (uuid) |
|
tender required
|
"cash" | "card" | "ebt_snap" | "ebt_cash" | "gift_card" | "online" | "other" |
online is a preorder's payment captured at hand-over (spec/PAYMENTS_ONLINE.md), read as other by an app before 1.1. |
amount_minor required
|
integer (int64) |
At most 10^15 (spec/API.md, Payments; 422 amount_too_large). |
provider required
|
string | null |
|
provider_ref required
|
string | null |
|
card_brand required
|
string | null |
|
card_last4 required
|
string | null |
|
authorization_code required
|
string | null |
Receipt object
id required
|
string (uuid) |
|
number required
|
integer (int64) |
|
kind required
|
"sale" | "refund" | "void" |
|
original_receipt_id required
|
string (uuid) | null |
|
shift_id required
|
string (uuid) |
|
workplace_id required
|
string (uuid) |
|
cashier_id required
|
string (uuid) |
|
currency required
|
string |
|
created_at required
|
string (date-time) |
|
lines required
|
array of ReceiptLine |
|
taxes required
|
array of ReceiptTax |
|
gross_total required
|
integer (int64) |
|
discount_total required
|
integer (int64) |
|
net_total required
|
integer (int64) |
|
tax_total required
|
integer (int64) |
|
total required
|
integer (int64) |
|
cash_due required
|
integer (int64) | null |
|
payments required
|
array of Payment |
|
change_minor required
|
integer (int64) |
|
needs_review required
|
boolean |
|
offline required
|
OfflineInfo | null |
|
order_type required
|
"dine_in" | "take_out" | "delivery" | null |
How a food-service order leaves; null for retail (spec/FOOD_SERVICE.md). |
tip_minor required
|
integer (int64) |
Sale: added to what the payments cover; not part of the total, untaxed. At most 10^15 (spec/API.md, Payments). |
deposit_total required
|
integer (int64) |
|
snap_total required
|
integer (int64) |
What the ebt_snap payments paid, exempt from sales tax. |
healthcare_total required
|
integer (int64) |
The FSA- and HSA-eligible lines' net and tax (spec/PHARMACY.md). |
rx_total required
|
integer (int64) |
|
order_label required
|
string | null |
|
deliveries required
|
array of ReceiptDelivery |
|
serial_conflicts
|
array of string |
A receipt closed offline, the serials it sold that a sale online would have refused. |
fiscal required
|
ReceiptFiscal | null |
The fiscal document of the receipt; null without a fiscal back end (spec/FISCAL.md). |
customer_id required
|
string (uuid) | null |
|
loyalty required
|
ReceiptLoyalty | null |
|
partner required
|
ReceiptPartner | null |
|
check required
|
ReceiptCheck | null |
The restaurant check it paid lines of (spec/RESTAURANT.md, Split and close); null otherwise. |
preorder
|
string (uuid) | null |
The preorder it handed over (spec/PREORDERS.md); null otherwise, and absent from a node before 1.1. |
service_charges required
|
array of ReceiptServiceCharge |
Every service charge the receipt carries, removed ones included, as they were at the sale; a refund's, what it took back of each (spec/API.md, Service charges). |
service_charge_total required
|
integer (int64) |
The charges that apply, inside total; 0 without (spec/RECEIPT_MATH.md, Service charges). |
CalculateRequest object
The input of a receipt fixture (spec/RECEIPT_MATH.md, schemas/receipt-fixtures.schema.json), within the math's bounds (spec/RECEIPT_MATH.md, Bounds) and 256 KiB.
CalculateResult object
The expected of a receipt fixture.
ReceiptPage object
items required
|
array of Receipt |
|
next required
|
string | null |
PsePurchaser object
The purchaser of a PSE product as the scanned ID gives it (spec/PHARMACY.md, "The purchaser").
name required
|
string |
|
address required
|
string |
|
date_of_birth required
|
string (date) |
|
id_type required
|
"driver_license" | "state_id" | "passport" | "military_id" | "other" |
|
id_state required
|
string |
The issuing state or country, as printed. |
id_number required
|
string |
|
signed required
|
boolean |
The purchaser signed the logbook entry. |
ReceiptSend object
channel required
|
"email" | "sms" |
|
to required
|
string |
An e-mail address, or a phone number in E.164 form; never stored. |
ReceiptDelivery object
id required
|
string (uuid) |
|
channel required
|
"email" | "sms" |
|
to_masked required
|
string |
|
status required
|
"queued" | "sent" | "failed" |
|
created_at required
|
string (date-time) |
|
sent_at required
|
string (date-time) | null |
|
error required
|
string | null |
A short reason when the send failed. |
ReceiptLoyalty object
What the receipt's loyalty steps did (spec/LOYALTY.md, The sale).
card_number_masked required
|
string | null |
|
unresolved_card required
|
boolean |
A card number recorded offline that found no one. |
points_spent required
|
integer (int64) |
|
points_value_minor required
|
integer (int64) |
|
points_earned required
|
integer (int64) |
|
stamps required
|
array of object |
|
voucher_id required
|
string (uuid) | null |
|
voucher_code required
|
string | null |
ReceiptPartner object
The partner and rate as they were at the sale (spec/LOYALTY.md, Partner codes).
partner_id required
|
string (uuid) |
|
code required
|
string |
|
commission_ppm required
|
integer |
|
commission_minor required
|
integer (int64) |
ReceiptPointsInput object
points required
|
integer (int64) |
|
hold_id required
|
string (uuid) |
ReceiptStampHold object
program_id required
|
string (uuid) |
|
hold_id required
|
string (uuid) |
ReceiptGiftCardHold object
original_line_no required
|
integer |
The gift card line of the original sale this unloads. |
hold_id required
|
string (uuid) |
A gift_card hold for the line's loaded amount (POST /v1/loyalty/holds). |
ReceiptVoucherInput object
code required
|
string |
|
hold_id
|
string (uuid) | null |
ReceiptCheckInput object
The check a sale pays lines of (spec/RESTAURANT.md, Split and close).
check_id required
|
string (uuid) |
|
version required
|
integer (int64) |
The check's version the receipt was figured at; compared online, not on an offline replay. |
split required
|
ReceiptCheckSplit |
ReceiptCheckSplit object
kind required
|
"none" | "items" | "seats" | "equal" |
|
seat
|
integer | null |
seats: the seat this receipt is; null for the shared lines. |
parts
|
integer | null |
equal, or the shared lines of seats: how many parts its due was cut into. |
ReceiptCheck object
The check a receipt paid lines of.
check_id required
|
string (uuid) |
|
check_number required
|
integer (int64) |
|
table_id required
|
string (uuid) | null |
|
table_name required
|
string | null |
|
area_id required
|
string (uuid) | null |
|
waiter_id required
|
string (uuid) |
|
covers required
|
integer |
|
opened_at required
|
string (date-time) |
|
split required
|
ReceiptCheckSplit |
|
closing required
|
boolean |
This receipt paid the check's last line and closed it. |
conflict required
|
boolean |
An offline receipt that did not apply to its check (spec/RESTAURANT.md, Offline). |
version required
|
integer (int64) | null |
The check's version after this receipt; the next receipt of a split names it. |
ServiceChargeHow "automatic" | "added" | "removed"
automatic (its conditions hold), added by hand, or removed by hand with a reason.
automatic · added · removed
ServiceChargePart object
A charge as one item line a fiscal back end gets (spec/FISCAL.md); one per set of tax codes.
tax_codes required
|
array of string |
|
amount_minor required
|
integer (int64) |
ReceiptServiceChargeInput object
id required
|
string |
|
how required
|
ServiceChargeHow |
|
reason
|
string | null |
removed: why, 1 to 200 characters (422 reason_required). |
ReceiptServiceCharge object
A service charge as the receipt keeps it (spec/API.md, Service charges).
id required
|
string |
|
label required
|
string |
In the receipt language at the sale. |
notice required
|
string |
In the receipt language at the sale; empty for none. |
rate_ppm required
|
integer |
|
how required
|
ServiceChargeHow |
|
reason required
|
string | null |
|
base required
|
"after_discounts" | "before_discounts" |
|
base_minor required
|
integer (int64) | null |
What the rate was applied to; null on a refund. |
amount_minor required
|
integer (int64) |
Inside total; 0 for a removed charge. |
tax_minor required
|
integer (int64) |
|
parts required
|
array of ServiceChargePart |
|
to_staff_ppm required
|
integer |
|
to_staff_minor required
|
integer (int64) |
round(the charge without its tax x to_staff_ppm / 1 000 000), fixed at the sale (spec/REPORTS.md, Service charges). |