Skip to main content

Products API

This documentation describes the snabble API endpoints related to the management and simple access of products. These endpoints are available on the api subdomain.

See General API access for information about API access.

Single product operations

Multiple products

Other operations

Data Model

A product represents a good that can be bought in a shop. The product contains all data which is needed to perform the checkout process.

Products might be prepackaged, like a box of pasta, which is identified by a code (ie. an EAN-13) that is printed on the packaging. In some cases the bought quantity is not known upfront. These products are modeled as weighable products (which also include products that are sold by other measures). Finally, there are deposit products and products that bundle other products, ie. a box of water bottles.

Weighable Products

The term weighable product is not precise. Weighable products should be used to map all kinds of not prepackaged products. These might be products like fruits that are priced by weight, but also ropes that are priced by their length or milk that is priced by volume. The mechanism can also be used to model bundles like a bag of bread rolls or instore EANs simply naming the price of the product.

The price of a weighable product depends on information encoded into a scannable code. There are three cases:

  • The code contains the measurement in the encoding unit. This measurement gets converted into the reference unit which allows the calculation of the price

  • The code contains the units in a prepackaged container or bag

  • The code contains the price

This information is extracted using the Code Templates described below.

Supported Units

The supported units are:

AbbreviationDescription
mlMilliliter
clCentiliter
dlDeciliter
lLiter
m3Cubic meter
cm3Cubic centimeter
m2Square meter
m2e-1Square meter × 10e-1
dm2Square decimeter
m2e-3Square meter × 10e-3
cm2Square centimeter
mmMillimeter
cmCentimeter
dmDecimeter
mMeter
gGram
dagDecagram
hgHectogram
kgKilogram
tTonne
pieceThe encoded number should be interpreted as number of contained units, i.e. number of bread rolls in a package
priceThe encoded number should be interpreted as total price, i.e. price of a package of different sausages

Code Template

Code templates are a way to extract information that is embedded into a scanned code. For example a instore EAN-13 has the format 2xxxxxCeeeeeC where the five x encode an identifier for the product, the five e encode the the information and the C are the checksums defined by the standard. With this and the additional information contained in the product, it is possible to calculate the price.

For example: Given the scanned code 2123455005005. By using the template it is possible to extract the identifier 12345 and the embeded information 00500. A product lookup might yield, that this code belongs to the product Banana which has a price of 2.00 €, g as encoding unit and kg as reference unit. With this information it is possible to calculate the price: 00500 → 500g → 0,5 kg × 2.00 € → 1 €.

TemplateDescription
defaultThe default template, matches anything
ean14_code128An EAN-14 embedded in a Code128 with Application Identifier "01"
ean13_instoreAn in-store EAN-13 with embedded data, but no internal checksum
ean13_instore_chkAn in-store EAN-13 with embedded data and internal checksum
german_printGerman newspapers/magazines with embedded price

Deposits

All products might reference a deposit, which is automatically added to shopping cart if an user buys the products. Deposit products can not be bought on their own.

Bundles

Bundles are products that contain other products, ie. a crate of beer bottles.

Sale restrictions

The supported sale restrictions are:

NameDescription
min_age_*Minimum age. Possible values min_age_6, min_age_12, min_age_14, min_age_16, min_age_18, min_age_21
fskProduct was rated by the german "Freiwillige Selbstkontrolle der Filmwirtschaft" (FSK)

Product Object

A product has two different representations. The first Product Object v2 is newer and supports more features. The second Product Object v1 is deprecated and should not be used anymore.

The service uses content negotiation to distinguish between the representations. Please use Accept and Content-Type headers with the MIME types named below.

Product Object v2

MIME type: application/vnd.snabble.product.v2+json

Example:

{
"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"
}
]
}

Product attributes:

ParameterTypeDefaultDescription
skustringThe unique id for identification of the product
projectstringThe project
namestring""The display name of the product
descriptionstringnullA short description of the product
subtitlestringnullAn additional title line for individual use (e.g. brand information)
imageUrlstringnullThe full URL for a product image
depositProductstringnullThe SKU of the associated deposit product
bundledProductstringnullThe SKU of the product contained in the bundle
outOfStockboolfalseFlag to indicate if the product is currently available in markets
deletedboolfalseFlag to indicate that a product does not exist any longer
taxCategorystringnullIdentifier of the tax category
weighByCustomerboolfalseFlag, if the product is prepackaged, or the customer has to do weighting by himself
referenceUnitstringnullThe unit in which the price attribute is calculated (e.g. "kg" where price is EUR/Kg)
encodingUnitstringnullUnit which is used as encoding within the EAN (e.g. "g" when the EAN contains grams)
codes[]object[]Array of code objects
productTypestring"default"Type of the product: "default", "weighable", "deposit"
controlIndicationnumber0Indication: -1 no control needed, 1 high control indication
forceControlboolfalseFlag to indicate if a control is necessary
saleRestrictionstringnullRestriction rules
saleStopboolfalseFlag 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.
pluSet[]stringnullPLU, the short code to identify a weighable product
scanMessagestringnullIdentifier of a message shown to the user after scanning a product (e.g. a product has more than one package )
notForSaleboolfalseFlag 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.
isDiscountableboolfalseFlag to indicate if the product should be considered for discounts

Code Object v2

NameTypeDefaultDescription
codestring""Scannable code / barcode
templatestring"default"Identifier of the code template used
isPrimaryboolnullIf a product has a code marked as primary this code is always presented to a POS instead of the scanned one. A product is not allowed to have more than one primary code. Optional.
transmissionCodestringnullIn case the POS cannot handle the scannable code / barcode, it contains a POS friendly code. Should not be used in combination with primary codes.
encodingUnitstringnullUnit which is used as encoding within the scanned code. Overwrites the property of the product
specifiedQuantitynumbernullIf set the code identifies the specified quantity of products instead of a single one. Optional.

Product Object v1

Deprecated: Please, use the model v2 and the Pricing API. If there is any reason you need to use this representation please contact us.

Product List v2

MIME type: application/vnd.snabble.product.list.v2+json

Example:

{
"products": [
{
"sku" : "1120325205",
"name" : "Premium-Holzöl",
// …
}
]
}
ParameterTypeDescription
products[]objectList of Product Object v2

Product JSON Stream v2

MIME type: application/vnd.snabble.product.v2+x-ndjson

A newline delimited JSON stream of Product Object v2.

Result Message

Result messages are simple status objects which are returned for batch operations.

ParameterTypeDescription
skustringThe product referenced by the result message
statusstringThe processing status: "ok" or "error"
messagestringA human-readable message describing the processing status

Statistics Object

Statistics objects are a simple representation of the product statistics.

ParameterTypeDescription
countintThe total product count
createdintThe amount of newly created products
updatedintThe amount of updated products
deletedintThe amount of deleted products
inStockintThe amount of products that are in stock

Get product

GET /{project}/products/sku/{sku}

Return one product by sku.

Required permissions : productsRead

Success Response 200 OK

Produces :


Create product

POST /{project}/products

Create or update a product. If the product already exists, it will be updated.

Required permissions : productsWrite

Request

Consumes :

Success Response 201 Created

no content


Update product

PUT /{project}/products/sku/{sku}

Create or update a product. The sku in the url parameter and the JSON payload have to match.

Required permissions : productsWrite

Request

Consumes :

Success Response 200 OK

no content


DELETE product

DELETE /{project}/products/sku/{sku}

Delete a product.

Required permissions : productsWrite

Success Response 204 No Content

no content


Find product by PLU

GET /{project}/products/plu/{plu}

Returns one product by PLU

Required permissions : productsRead

Success Response 200 OK

Produces :


Batch import

POST /{project}/products/_batch

Import a list of products in one HTTP request.

Required permissions : productsWrite

Request

Maximal batch size : 20000 items

Success Response 200 OK

Content-Type : application/x-ndjson

Data : JSON stream of result messages.


Request products

GET /{project}/products

Return all products of a project as JSON stream.

Required permissions : productsRead

Request

Parameters :

All parameters are optional.

NameDescription
limitSets a limit of products returned. Must be a positive number.
qPasses a 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.

Success Response 200 OK

Produces :


Delete products

DELETE /{project}/products

Deletes all products of a project.

Required permissions : productsWrite

Request

Example: DELETE /example-project/products

Success Response 200 OK


Get statistics

GET /{project}/products/statistics

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

Required permissions : productsRead

Request

Parameters :

NameDescription
sinceThe starting date of the time period. This parameter is required.

Success Response 200 OK