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.

The detailed endpoints and payloads of the products API is described in the OpenAPI specification.

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 in-store 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:

m3Cubic meter
cm3Cubic centimeter
m2Square meter
m2e-1Square meter × 10e-1
dm2Square decimeter
m2e-3Square meter × 10e-3
cm2Square centimeter
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 in-store 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 embedded 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 €.

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

Previous product object version

The current representation of the product object is the second version. It is possible to represent products in the previous legacy version by using HTTP headers, but this is not recommended. If there is any reason you need to use the legacy representation, please contact us.