Product Service API (v1)

Download OpenAPI specification:Download

This documentation describes the snabble API endpoints related to the management and simple access of products.

Products

Manage and access product data.

Get products

Return a batch of products. If no products are found, the response is empty.

Authorizations:

bearerAuth

path Parameters

projectID

required

string (ProjectID)

ID of the project

query Parameters

limit	integer Example: limit=100 Sets a limit of products returned. 0 is interpreted as no limit.
q	string Query string. Will do a full text search in the product name and description and will perform a prefix search with the product SKU, EAN and weighed item id. All products found by either search will be returned.

Responses

Response samples

200
400
default

Content type

application/x-ndjson

{"sku": "1120325205",
"project": "project",
"name": "Premium-Holzöl",
"description": "farblos, 750ml",
"subtitle": "Aplina",
"taxCategory": "normal",
"imageUrl": "https://www.example.com/some/image.jpg",
"productType": "default",
"controlIndication": 0.4,
"saleRestriction": "min_age_18",
"saleStop": true,
"notForSale": true,
"isDiscountable": true,
"scanMessage": "multipack-2",
"codes": [{"code": "0654203316514",
"transmissionCode": "1234203316514",
"template": "default"
}
],
"additionalAttributes": {"this": "that",
"foo": "bar"
}
}

Create new product

Authorizations:

bearerAuth

path Parameters

projectID

required

string (ProjectID)

ID of the project

Request Body schema: application/json

sku required	string (SKU) SKU (Stock Keeping Unit) of a product. This must be distinct (primary key).
project	string (ProjectID) ID of the project
name	string The display name of the product
description	string A short description of the product
subtitle	string An additional title line for individual use (e.g. brand information)
imageURL	string The full URL for a product image
depositProduct	string The SKU of the associated deposit product. If a user scans a product with a deposit SKU, the latter will automatically be added to the cart. Deposit products can not be bought on their own.
bundledProduct	string The SKU of the product contained in the bundle. Bundles are products that contain other products, ie. a crate of beer bottles.
outOfStock	boolean Flag to indicate if the product is currently available in markets. Default is false.
deleted	boolean Flag to indicate that a product does not exist any longer. Default is false.
taxCategory	string Identifier of the tax category
weighByCustomer	boolean Flag, if the product is prepackaged, or the customer has to do weighting by themselves. Default is false.
referenceUnit	string Enum: "ml" "cl" "dl" "l" "m3" "cm3" "m2" "m2e-1" "dm2" "m2e-3" "cm2" "mm" "cm" "dm" "m" "g" "dag" "hg" "kg" "t" "piece" "price" The unit in which the price attribute is calculated (e.g. "kg" where price is EUR/Kg).
encodingUnit	string Enum: "ml" "cl" "dl" "l" "m3" "cm3" "m2" "m2e-1" "dm2" "m2e-3" "cm2" "mm" "cm" "dm" "m" "g" "dag" "hg" "kg" "t" "piece" "price" Unit which is used as encoding within the EAN (e.g. "g" when the EAN contains grams).
	Array of objects (Code) Object codes
productType	string Enum: "default" "weighable" "deposit" Type of the product. Default is "default".
controlIndication	number Indicates necessity of control. -1 no control needed, 1 high control indication. Default is 0, meaning the configured control probability applies.
forceControl	boolean Flag to indicate if a control is necessary. Default is false.
saleRestriction	string Enum: "min_age_6" "min_age_12" "min_age_14" "min_age_16" "min_age_18" "min_age_21" "fsk" Sales restrictions, usually minimum age being `min_age_` followed by a number. `fsk` means that the product was rated by the German "Freiwillige Selbstkontrolle der Filmwirtschaft".
saleStop	boolean Flag to indicate if there is a sale stop for this product. Flagged products can not be purchased and a default message will be shown This product cannot be paid for using the app.. Default is false.
pluSet	Array of strings (PLU) PLUs, short codes to identify a weighable product
scanMessage	string Identifier of a message shown to the user after scanning a product (e.g. a product has more than one package )
notForSale	boolean Flag to indicate if the product is not for sale. When scanning the product only the scan message will be shown. If there is no scan message This product cannot be paid for using the app, please pay for it at the cashier. will be displayed.. Default is false.
isDiscountable	boolean Flag to indicate if the product should be considered for discounts. Default is false.
priceEntryRequired	boolean Flag to indicate if the price of the product should be provided by the customer or the cashier. Default is false.
	object A string map of additional attributes for special use-cases.

Responses

Request samples

Payload

Content type

application/json

{"sku": "1120325205",
"project": "project",
"name": "Premium-Holzöl",
"description": "farblos, 750ml",
"subtitle": "Aplina",
"taxCategory": "normal",
"imageUrl": "https://www.example.com/some/image.jpg",
"productType": "default",
"controlIndication": 0.4,
"saleRestriction": "min_age_18",
"saleStop": true,
"notForSale": true,
"isDiscountable": true,
"scanMessage": "multipack-2",
"codes": [{"code": "0654203316514",
"transmissionCode": "1234203316514",
"template": "default"
}
],
"additionalAttributes": {"this": "that",
"foo": "bar"
}
}

Response samples

201
400
default

Content type

application/json

{"sku": "1120325205",
"project": "project",
"name": "Premium-Holzöl",
"description": "farblos, 750ml",
"subtitle": "Aplina",
"taxCategory": "normal",
"imageUrl": "https://www.example.com/some/image.jpg",
"productType": "default",
"controlIndication": 0.4,
"saleRestriction": "min_age_18",
"saleStop": true,
"notForSale": true,
"isDiscountable": true,
"scanMessage": "multipack-2",
"codes": [{"code": "0654203316514",
"transmissionCode": "1234203316514",
"template": "default"
}
],
"additionalAttributes": {"this": "that",
"foo": "bar"
}
}

Delete all products

Delete all products in a project.

Authorizations:

bearerAuth

path Parameters

projectID

required

string (ProjectID)

ID of the project

Responses

Response samples

default

Content type

application/json

{"error": {"type": "string",
"message": "string"
}
}

Get product with SKU

Authorizations:

bearerAuth

path Parameters

projectID required	string (ProjectID) ID of the project
sku required	string (SKU) SKU (Stock Keeping Unit) of a product. This must be distinct (primary key).

Responses

Response samples

200
404
default

Content type

application/json

{"sku": "1120325205",
"project": "project",
"name": "Premium-Holzöl",
"description": "farblos, 750ml",
"subtitle": "Aplina",
"taxCategory": "normal",
"imageUrl": "https://www.example.com/some/image.jpg",
"productType": "default",
"controlIndication": 0.4,
"saleRestriction": "min_age_18",
"saleStop": true,
"notForSale": true,
"isDiscountable": true,
"scanMessage": "multipack-2",
"codes": [{"code": "0654203316514",
"transmissionCode": "1234203316514",
"template": "default"
}
],
"additionalAttributes": {"this": "that",
"foo": "bar"
}
}

Create or update product with SKU

Updates a product with the given SKU, or creates it if it doesn't already exists.

Authorizations:

bearerAuth

path Parameters

projectID required	string (ProjectID) ID of the project
sku required	string (SKU) SKU (Stock Keeping Unit) of a product. This must be distinct (primary key).

Request Body schema: application/json

Note that the SKU in the request body must match the path parameter.

sku required	string (SKU) SKU (Stock Keeping Unit) of a product. This must be distinct (primary key).
project	string (ProjectID) ID of the project
name	string The display name of the product
description	string A short description of the product
subtitle	string An additional title line for individual use (e.g. brand information)
imageURL	string The full URL for a product image
depositProduct	string The SKU of the associated deposit product. If a user scans a product with a deposit SKU, the latter will automatically be added to the cart. Deposit products can not be bought on their own.
bundledProduct	string The SKU of the product contained in the bundle. Bundles are products that contain other products, ie. a crate of beer bottles.
outOfStock	boolean Flag to indicate if the product is currently available in markets. Default is false.
deleted	boolean Flag to indicate that a product does not exist any longer. Default is false.
taxCategory	string Identifier of the tax category
weighByCustomer	boolean Flag, if the product is prepackaged, or the customer has to do weighting by themselves. Default is false.
referenceUnit	string Enum: "ml" "cl" "dl" "l" "m3" "cm3" "m2" "m2e-1" "dm2" "m2e-3" "cm2" "mm" "cm" "dm" "m" "g" "dag" "hg" "kg" "t" "piece" "price" The unit in which the price attribute is calculated (e.g. "kg" where price is EUR/Kg).
encodingUnit	string Enum: "ml" "cl" "dl" "l" "m3" "cm3" "m2" "m2e-1" "dm2" "m2e-3" "cm2" "mm" "cm" "dm" "m" "g" "dag" "hg" "kg" "t" "piece" "price" Unit which is used as encoding within the EAN (e.g. "g" when the EAN contains grams).
	Array of objects (Code) Object codes
productType	string Enum: "default" "weighable" "deposit" Type of the product. Default is "default".
controlIndication	number Indicates necessity of control. -1 no control needed, 1 high control indication. Default is 0, meaning the configured control probability applies.
forceControl	boolean Flag to indicate if a control is necessary. Default is false.
saleRestriction	string Enum: "min_age_6" "min_age_12" "min_age_14" "min_age_16" "min_age_18" "min_age_21" "fsk" Sales restrictions, usually minimum age being `min_age_` followed by a number. `fsk` means that the product was rated by the German "Freiwillige Selbstkontrolle der Filmwirtschaft".
saleStop	boolean Flag to indicate if there is a sale stop for this product. Flagged products can not be purchased and a default message will be shown This product cannot be paid for using the app.. Default is false.
pluSet	Array of strings (PLU) PLUs, short codes to identify a weighable product
scanMessage	string Identifier of a message shown to the user after scanning a product (e.g. a product has more than one package )
notForSale	boolean Flag to indicate if the product is not for sale. When scanning the product only the scan message will be shown. If there is no scan message This product cannot be paid for using the app, please pay for it at the cashier. will be displayed.. Default is false.
isDiscountable	boolean Flag to indicate if the product should be considered for discounts. Default is false.
priceEntryRequired	boolean Flag to indicate if the price of the product should be provided by the customer or the cashier. Default is false.
	object A string map of additional attributes for special use-cases.

Responses

Request samples

Payload

Content type

application/json

{"sku": "1120325205",
"project": "project",
"name": "Premium-Holzöl",
"description": "farblos, 750ml",
"subtitle": "Aplina",
"taxCategory": "normal",
"imageUrl": "https://www.example.com/some/image.jpg",
"productType": "default",
"controlIndication": 0.4,
"saleRestriction": "min_age_18",
"saleStop": true,
"notForSale": true,
"isDiscountable": true,
"scanMessage": "multipack-2",
"codes": [{"code": "0654203316514",
"transmissionCode": "1234203316514",
"template": "default"
}
],
"additionalAttributes": {"this": "that",
"foo": "bar"
}
}

Response samples

200
400
default

Content type

application/json

{"sku": "1120325205",
"project": "project",
"name": "Premium-Holzöl",
"description": "farblos, 750ml",
"subtitle": "Aplina",
"taxCategory": "normal",
"imageUrl": "https://www.example.com/some/image.jpg",
"productType": "default",
"controlIndication": 0.4,
"saleRestriction": "min_age_18",
"saleStop": true,
"notForSale": true,
"isDiscountable": true,
"scanMessage": "multipack-2",
"codes": [{"code": "0654203316514",
"transmissionCode": "1234203316514",
"template": "default"
}
],
"additionalAttributes": {"this": "that",
"foo": "bar"
}
}

Delete product with SKU

Authorizations:

bearerAuth

path Parameters

projectID required	string (ProjectID) ID of the project
sku required	string (SKU) SKU (Stock Keeping Unit) of a product. This must be distinct (primary key).

Responses

Response samples

404
default

Content type

application/json

{"error": {"type": "string",
"message": "string"
}
}

Get product by PLU

Authorizations:

bearerAuth

path Parameters

projectID required	string (ProjectID) ID of the project
plu required	string (PLU) PLU (Price Look-up) of a product. A PLU can only be assigned to one product. If a PLU is assigned to multiple products in a batch, it will only be applied to one of them.

Responses

Response samples

200
404
default

Content type

application/json

{"sku": "1120325205",
"project": "project",
"name": "Premium-Holzöl",
"description": "farblos, 750ml",
"subtitle": "Aplina",
"taxCategory": "normal",
"imageUrl": "https://www.example.com/some/image.jpg",
"productType": "default",
"controlIndication": 0.4,
"saleRestriction": "min_age_18",
"saleStop": true,
"notForSale": true,
"isDiscountable": true,
"scanMessage": "multipack-2",
"codes": [{"code": "0654203316514",
"transmissionCode": "1234203316514",
"template": "default"
}
],
"additionalAttributes": {"this": "that",
"foo": "bar"
}
}

Find SKUs for PLU Prefix

Authorizations:

bearerAuth

path Parameters

projectID

required

string (ProjectID)

ID of the project

query Parameters

plu-prefix

required

string

Partial PLU. Performs a case-insensitive prefix search for the given input.

Responses

Response samples

200
404

Content type

application/json

["123456789",
"1120325205"
]

Batch update of products

Import an ndjson batch of product objects. Maximal batch size is 20000 items.

If any of the individual product updates cannot be processed, the service will still return status code 200. It is therefore important to inspect the response and the status codes within.

Note that it is not possible to express ndjson in OpenAPI, so only a single entry is expressed here. Multiple entries are separated by linebreaks.

Authorizations:

bearerAuth

path Parameters

projectID

required

string (ProjectID)

ID of the project

Request Body schema: application/x-ndjson
required

sku required	string (SKU) SKU (Stock Keeping Unit) of a product. This must be distinct (primary key).
project	string (ProjectID) ID of the project
name	string The display name of the product
description	string A short description of the product
subtitle	string An additional title line for individual use (e.g. brand information)
imageURL	string The full URL for a product image
depositProduct	string The SKU of the associated deposit product. If a user scans a product with a deposit SKU, the latter will automatically be added to the cart. Deposit products can not be bought on their own.
bundledProduct	string The SKU of the product contained in the bundle. Bundles are products that contain other products, ie. a crate of beer bottles.
outOfStock	boolean Flag to indicate if the product is currently available in markets. Default is false.
deleted	boolean Flag to indicate that a product does not exist any longer. Default is false.
taxCategory	string Identifier of the tax category
weighByCustomer	boolean Flag, if the product is prepackaged, or the customer has to do weighting by themselves. Default is false.
referenceUnit	string Enum: "ml" "cl" "dl" "l" "m3" "cm3" "m2" "m2e-1" "dm2" "m2e-3" "cm2" "mm" "cm" "dm" "m" "g" "dag" "hg" "kg" "t" "piece" "price" The unit in which the price attribute is calculated (e.g. "kg" where price is EUR/Kg).
encodingUnit	string Enum: "ml" "cl" "dl" "l" "m3" "cm3" "m2" "m2e-1" "dm2" "m2e-3" "cm2" "mm" "cm" "dm" "m" "g" "dag" "hg" "kg" "t" "piece" "price" Unit which is used as encoding within the EAN (e.g. "g" when the EAN contains grams).
	Array of objects (Code) Object codes
productType	string Enum: "default" "weighable" "deposit" Type of the product. Default is "default".
controlIndication	number Indicates necessity of control. -1 no control needed, 1 high control indication. Default is 0, meaning the configured control probability applies.
forceControl	boolean Flag to indicate if a control is necessary. Default is false.
saleRestriction	string Enum: "min_age_6" "min_age_12" "min_age_14" "min_age_16" "min_age_18" "min_age_21" "fsk" Sales restrictions, usually minimum age being `min_age_` followed by a number. `fsk` means that the product was rated by the German "Freiwillige Selbstkontrolle der Filmwirtschaft".
saleStop	boolean Flag to indicate if there is a sale stop for this product. Flagged products can not be purchased and a default message will be shown This product cannot be paid for using the app.. Default is false.
pluSet	Array of strings (PLU) PLUs, short codes to identify a weighable product
scanMessage	string Identifier of a message shown to the user after scanning a product (e.g. a product has more than one package )
notForSale	boolean Flag to indicate if the product is not for sale. When scanning the product only the scan message will be shown. If there is no scan message This product cannot be paid for using the app, please pay for it at the cashier. will be displayed.. Default is false.
isDiscountable	boolean Flag to indicate if the product should be considered for discounts. Default is false.
priceEntryRequired	boolean Flag to indicate if the price of the product should be provided by the customer or the cashier. Default is false.
	object A string map of additional attributes for special use-cases.

Responses

Request samples

Payload

Content type

application/x-ndjson

{"sku": "1120325205",
"project": "project",
"name": "Premium-Holzöl",
"description": "farblos, 750ml",
"subtitle": "Aplina",
"taxCategory": "normal",
"imageUrl": "https://www.example.com/some/image.jpg",
"productType": "default",
"controlIndication": 0.4,
"saleRestriction": "min_age_18",
"saleStop": true,
"notForSale": true,
"isDiscountable": true,
"scanMessage": "multipack-2",
"codes": [{"code": "0654203316514",
"transmissionCode": "1234203316514",
"template": "default"
}
],
"additionalAttributes": {"this": "that",
"foo": "bar"
}
}

Response samples

200
400
409
default

Content type

application/x-ndjson

{"sku": "1120325205",
"status": "ok"
}

Availabilities

Manage and inspect which products are in stock or not available.

Retrieve availabilites

Retrieve availabilites for a product. Note that it will always respond with availabilities, regardless of whether the project and product actually exists or not.

Authorizations:

bearerAuth

path Parameters

projectID required	string (ProjectID) ID of the project
sku required	string (SKU) SKU (Stock Keeping Unit) of a product. This must be distinct (primary key).

Responses

Response samples

200
default

Content type

application/json

[{"shopID": "1234",
"project": "a-project",
"sku": "12345",
"value": "notAvailable"
},
{"shopID": "1235",
"project": "a-project",
"sku": "12345",
"value": "listed"
},
{"shopID": "1236",
"project": "a-project",
"sku": "12345",
"value": "inStock"
}
]

Create or update availabilities

Create or update availabilities for a product.

Authorizations:

bearerAuth

path Parameters

projectID required	string (ProjectID) ID of the project
sku required	string (SKU) SKU (Stock Keeping Unit) of a product. This must be distinct (primary key).

Request Body schema: application/json
required

Array

shopID required	string (ShopID) The ID of the Shop in which the availability applies.
value required	string (AvailabilityValue) Enum: "inStock" "listed" "notAvailable" Classifies the availability for the product in a given sh0op

Responses

Request samples

Payload

Content type

application/json

{"value": [{"shopID": "1234",
"value": "notAvailable"
},
{"shopID": "1235",
"value": "listed"
},
{"shopID": "1236",
"value": "inStock"
}
]
}

Response samples

200
400
default

Content type

application/json

[{"shopID": "1234",
"project": "a-project",
"sku": "12345",
"value": "notAvailable"
},
{"shopID": "1235",
"project": "a-project",
"sku": "12345",
"value": "listed"
},
{"shopID": "1236",
"project": "a-project",
"sku": "12345",
"value": "inStock"
}
]

Availability batch operation

Availability batch operation for products in a project.

Authorizations:

bearerAuth

path Parameters

projectID

required

string (ProjectID)

ID of the project

Request Body schema: application/x-ndjson
required

op	string Enum: "put" "delete"
	object (AvailabilityBatchParams) Availability parameters for updating or deleting availabilities in batch

Responses

Request samples

Payload

Content type

application/x-ndjson

{"op": "delete",
"availability": {"shopID": "1234",
"project": "a project",
"sku": "123456789"
}
}

Response samples

200
400
default

Content type

application/json

{"availability": {"shopID": "string",
"value": "inStock",
"project": "string",
"sku": "string"
},
"status": "ok",
"message": "string"
}

Statistics

Statistics about products.

Get products statistics

Return simple statistics about the products in a time period ranging from a selected date until now.

Authorizations:

bearerAuth

path Parameters

projectID

required

string (ProjectID)

ID of the project

query Parameters

since

string

Example: since=2022-04-23T18:25:43.511Z

ISO 8601 timestamp

Responses

Response samples

200
400
default

Content type

application/json

{"inStock": 240,
"created": 122,
"updated": 247,
"deleted": 8,
"count": 240
}

Product Service API (v1)

Products

Get products

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Create new product

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Delete all products

Authorizations:

path Parameters

Responses

Response samples

Get product with SKU

Authorizations:

path Parameters

Responses

Response samples

Create or update product with SKU

Authorizations:

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Delete product with SKU

Authorizations:

path Parameters

Responses

Response samples

Get product by PLU

Authorizations:

path Parameters

Responses

Response samples

Find SKUs for PLU Prefix

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Batch update of products

Authorizations:

path Parameters

Request Body schema: application/x-ndjsonrequired

Responses

Request samples

Response samples

Availabilities

Retrieve availabilites

Authorizations:

path Parameters

Responses

Response samples

Create or update availabilities

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Availability batch operation

Authorizations:

path Parameters

Request Body schema: application/x-ndjsonrequired

Responses

Request samples

Response samples

Statistics

Get products statistics

Authorizations:

path Parameters

query Parameters

Request Body schema: application/x-ndjson
required

Request Body schema: application/json
required

Request Body schema: application/x-ndjson
required