iRetail PRO store node 1.0.0-m1: items

11 operations

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

Operations

GET /v1/items Items with this store's prices.

operationId listItems · 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).
`q`	query	`string`	Search in names, SKU, PLU, barcodes.
`group_id`	query	`string (uuid)`	Group.
`active`	query	`boolean`	Only active or inactive.
`parent_id`	query	`string (uuid)`	A parent's variants (spec/VARIANTS.md).
`kind_of`	query	`"parent" \| "variant" \| "plain"`	Only parents, only variants, or only items that are neither.
`limit`	query	`integer`	Page size, 1–200.
`after`	query	`string`	Cursor from the previous page.

Responses

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

POST /v1/items Create an item.

operationId createItem · Permission item.edit

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).
`Approval-Token`	header	`string`	One-time approval from POST /v1/approvals for this operation's permission.

Request body required

application/json ItemCreate

Responses

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

GET /v1/items/lookup Resolve a scanned or typed code: barcode, pack barcode, variable-measure barcode, PLU or SKU.

For a code the app knows is a product's (its own catalog copy has it, or it has a product barcode's shape). A scan the app did not find may be a loyalty card, a gift card or a voucher code, and goes by POST, never in a URL (spec/API.md, Transport).

operationId lookupItem · 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).
`code` required	query	`string`	The code.

Responses

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

POST /v1/items/lookup The same lookup with the code in the body.

The form an app uses for any scan its own catalog copy did not find: such a code may be a loyalty card, a gift card or a voucher code, and a URL's query is kept by proxies and access logs (spec/API.md, Transport). The same permission and answer as GET; the node logs no code.

operationId lookupItemPost · 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).

Request body required

application/json ItemLookup

Responses

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

GET /v1/items/{id} One item.

operationId getItem · 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).
`id` required	path	`string (uuid)`	Id.

Responses

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

PATCH /v1/items/{id} Change an item.

operationId patchItem · Permission item.edit

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.
`Approval-Token`	header	`string`	One-time approval from POST /v1/approvals for this operation's permission.

Request body required

application/json ItemPatch

Responses

200 OK Item
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/items/{id}/variants Make the variants a parent lacks (spec/VARIANTS.md).

operationId createVariants · Permission item.edit

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.
`Approval-Token`	header	`string`	One-time approval from POST /v1/approvals for this operation's permission.

Request body required

application/json VariantsCreate

Responses

201 The variants made, in order. VariantsCreated
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

PUT /v1/items/{id}/price Set this store's price of an item.

operationId putPrice · Permission price.edit

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.
`Approval-Token`	header	`string`	One-time approval from POST /v1/approvals for this operation's permission.

Request body required

application/json PricePut

Responses

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

POST /v1/item-photos Keep a JPEG or WebP photo of at most 512 KB for an item to name, its EXIF and XMP removed (spec/PUBLIC_API.md, The storefront); kept by the catalog's owner, 409 owned_by_hub at a store of a chain.

operationId uploadItemPhoto · Permission item.edit

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

image/jpeg string (binary)
image/webp string (binary)

Responses

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

GET /v1/item-photos/{id} An item photo's bytes with its ETag; 304 for a matching If-None-Match; photos do not cross to stores of a chain (404 there).

operationId getItemPhoto · 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).
`id` required	path	`string (uuid)`
`If-None-Match`	header	`string`	The ETag the caller holds.

Responses

200 The photo. string (binary)
304 Not modified.
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error

DELETE /v1/item-photos/{id} Delete a photo no item names (409 photo_in_use otherwise).

operationId deleteItemPhoto · Permission item.edit

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)`

Responses

204 Done
401 Error (spec/API.md). Error
403 Error (spec/API.md). Error
404 Error (spec/API.md). Error
409 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.

`Barcode` object

A barcode of the item or of a pack of it.

`barcode` required	`string`
`pack_quantity_milli` required	`integer (int64)`

`StorePrice` object

`price_minor` required	`integer (int64)`
`currency` required	`string`

`ModifierOption` object

`id` required	`string`
`name` required	`LocalizedText`
`price_delta_minor` required	`integer (int64)`	Added to the item's price; may be negative.

`ModifierGroup` object

`id` required	`string`
`name` required	`LocalizedText`
`min` required	`integer`
`max` required	`integer`
`options` required	`array of ModifierOption`

`Item` object

`id` required	`string (uuid)`
`sku` required	`string`
`plu` required	`string \| null`
`name` required	`LocalizedText`
`kind` required	`"piece" \| "weighed" \| "variable_weight" \| "service" \| "kit" \| "gift_card"`	A kit takes its components' stock at the sale (spec/STOCK.md, Kits); a gift card line sells stored value (spec/LOYALTY.md, Gift cards).
`base_unit` required	`"each" \| "kg" \| "lb" \| "l" \| "us_gal" \| "m" \| "ft"`
`tax_codes` required	`array of string`
`group_id` required	`string (uuid) \| null`
`profile` required	`string \| null`
`attributes` required	`object`	Profile fields (JSON), validated by the profile's schema.
`stock_policy` required	`"fifo" \| "fefo"`
`discountable` required	`boolean`
`active` required	`boolean`
`barcodes` required	`array of Barcode`
`modifier_groups` required	`array of ModifierGroup`	Options a line of the item takes (spec/FOOD_SERVICE.md).
`tags` required	`array of ItemTag`	The item's tags in the order of their ids (spec/SEARCH.md, Tags).
`price` required	`StorePrice \| null`
`variant_options` required	`array of VariantOption`	On a parent, its options in order (spec/VARIANTS.md); empty on every other item.
`parent_id` required	`string (uuid) \| null`	On a variant, its parent (spec/VARIANTS.md); set when the item is made.
`variant_values` required	`map of string \| null`	On a variant, a value code for each of the parent's option codes.
`serial_tracked` required	`boolean`	Each unit's serial is recorded at receiving, sale, return and write-off (spec/VARIANTS.md).
`photo_id`	`string (uuid) \| null`	The item's photo (POST /v1/item-photos) for the storefront, or null; absent from a node before 1.1.
`kit_components` required	`array of Component`	A kit's components, 1 to 20 (spec/STOCK.md, Kits); empty on every other item. Each is taxed as the kit is (its tax_category and tax_codes) and carries no deposit, or the save is refused with kit_tax_mixed.
`version` required	`integer (int64)`

`ItemCreate` object

`sku` required	`string`
`plu`	`string \| null`
`name` required	`LocalizedText`
`kind` required	`"piece" \| "weighed" \| "variable_weight" \| "service" \| "kit" \| "gift_card"`	A kit takes its components' stock at the sale (spec/STOCK.md, Kits); a gift card line sells stored value (spec/LOYALTY.md, Gift cards).
`base_unit` required	`"each" \| "kg" \| "lb" \| "l" \| "us_gal" \| "m" \| "ft"`
`tax_codes`	`array of string`
`group_id`	`string (uuid) \| null`
`profile`	`string \| null`
`attributes`	`object`	Profile fields (JSON), validated by the profile's schema.
`stock_policy`	`"fifo" \| "fefo"`
`discountable`	`boolean`
`active`	`boolean`
`barcodes`	`array of Barcode`
`modifier_groups`	`array of ModifierGroup`	Options a line of the item takes (spec/FOOD_SERVICE.md).
`tags`	`array of string (uuid)`	Tag ids; sets the item's tags (spec/SEARCH.md, Tags).
`variant_options`	`array of VariantOption`	On a parent, its options in order (spec/VARIANTS.md); empty on every other item.
`parent_id`	`string (uuid) \| null`
`variant_values`	`map of string \| null`	On a variant, a value code for each of the parent's option codes.
`serial_tracked`	`boolean`	Each unit's serial is recorded at receiving, sale, return and write-off (spec/VARIANTS.md).
`photo_id`	`string (uuid) \| null`	The item's photo (POST /v1/item-photos) for the storefront, or null; absent from a node before 1.1.
`kit_components`	`array of Component`	A kit's components, 1 to 20 (spec/STOCK.md, Kits); empty on every other item. Each is taxed as the kit is (its tax_category and tax_codes) and carries no deposit, or the save is refused with kit_tax_mixed.

`ItemPatch` object

`sku`	`string`
`plu`	`string \| null`
`name`	`LocalizedText`
`kind`	`"piece" \| "weighed" \| "variable_weight" \| "service" \| "kit" \| "gift_card"`	A kit takes its components' stock at the sale (spec/STOCK.md, Kits); a gift card line sells stored value (spec/LOYALTY.md, Gift cards).
`base_unit`	`"each" \| "kg" \| "lb" \| "l" \| "us_gal" \| "m" \| "ft"`
`tax_codes`	`array of string`
`group_id`	`string (uuid) \| null`
`profile`	`string \| null`
`attributes`	`object`	Profile fields (JSON), validated by the profile's schema.
`stock_policy`	`"fifo" \| "fefo"`
`discountable`	`boolean`
`active`	`boolean`
`barcodes`	`array of Barcode`
`modifier_groups`	`array of ModifierGroup`	Options a line of the item takes (spec/FOOD_SERVICE.md).
`tags`	`array of string (uuid)`	Tag ids; sets the item's tags (spec/SEARCH.md, Tags).
`variant_options`	`array of VariantOption`	On a parent, its options in order (spec/VARIANTS.md); empty on every other item.
`variant_values`	`map of string \| null`	On a variant, a value code for each of the parent's option codes.
`serial_tracked`	`boolean`	Each unit's serial is recorded at receiving, sale, return and write-off (spec/VARIANTS.md).
`photo_id`	`string (uuid) \| null`	The item's photo (POST /v1/item-photos) for the storefront, or null; absent from a node before 1.1.
`kit_components`	`array of Component`	A kit's components, 1 to 20 (spec/STOCK.md, Kits); empty on every other item. Each is taxed as the kit is (its tax_category and tax_codes) and carries no deposit, or the save is refused with kit_tax_mixed.

`VariantValue` object

`code` required	`string`
`name` required	`LocalizedText`

`VariantOption` object

`code` required	`string`
`name` required	`LocalizedText`
`values` required	`array of VariantValue`

`VariantsCreate` object

`combinations` required	`array of map of string \| null`	Option code to value code for each variant to make; null for every combination.
`price_minor` required	`integer (int64) \| null`	The variants' price; null for the parent's.

`VariantsCreated` object

items required array of Item

`PricePut` object

price_minor required integer (int64)

`Lookup` object

What a scanned or typed code means; quantity and price come from a pack or a variable-measure barcode.

`item` required	`Item`
`source` required	`"barcode" \| "pack_barcode" \| "variable_measure" \| "plu" \| "sku"`
`quantity_milli` required	`integer (int64) \| null`
`price_minor` required	`integer (int64) \| null`

`ItemPage` object

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

`ItemTag` object

`tag_id` required	`string (uuid)`
`source` required	`"manual" \| "suggested"`
`confidence` required	`integer \| null`	The accepted suggestion's confidence; null when manual.

`Component` object

A kit's or a recipe's component: how much of the item (spec/STOCK.md).

`item_id` required	`string (uuid)`
`quantity_milli` required	`integer (int64)`

`ItemLookup` object

A scanned or typed code; never logged or kept.

code required string As scanned or typed, the same text GET's code takes.

`ItemPhoto` object

`id` required	`string (uuid)`
`content_type` required	`"image/jpeg" \| "image/webp"`
`bytes` required	`integer`
`width` required	`integer`
`height` required	`integer`
`etag` required	`string`
`created_at` required	`string (date-time)`

iRetail PRO store node 1.0.0-m1: items

Operations

Parameters

Responses

Parameters

Request body required

Responses

Parameters

Responses

Parameters

Request body required

Responses

Parameters

Responses

Parameters

Request body required

Responses

Parameters

Request body required

Responses

Parameters

Request body required

Responses

Parameters

Request body required

Responses

Parameters

Responses

Parameters

Responses

Schemas

Error object

LocalizedText map of string

Barcode object

StorePrice object

ModifierOption object

ModifierGroup object

Item object

ItemCreate object

ItemPatch object

VariantValue object

VariantOption object

VariantsCreate object

VariantsCreated object

PricePut object

Lookup object

ItemPage object

ItemTag object

Component object

ItemLookup object

ItemPhoto object

`Error` object

`LocalizedText` map of string

`Barcode` object

`StorePrice` object

`ModifierOption` object

`ModifierGroup` object

`Item` object

`ItemCreate` object

`ItemPatch` object

`VariantValue` object

`VariantOption` object

`VariantsCreate` object

`VariantsCreated` object

`PricePut` object

`Lookup` object

`ItemPage` object

`ItemTag` object

`Component` object

`ItemLookup` object

`ItemPhoto` object