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:
| Abbreviation | Description |
|---|---|
| ml | Milliliter |
| cl | Centiliter |
| dl | Deciliter |
| l | Liter |
| m3 | Cubic meter |
| cm3 | Cubic centimeter |
| m2 | Square meter |
| m2e-1 | Square meter × 10e-1 |
| dm2 | Square decimeter |
| m2e-3 | Square meter × 10e-3 |
| cm2 | Square centimeter |
| mm | Millimeter |
| cm | Centimeter |
| dm | Decimeter |
| m | Meter |
| g | Gram |
| dag | Decagram |
| hg | Hectogram |
| kg | Kilogram |
| t | Tonne |
| piece | The encoded number should be interpreted as number of contained units, i.e. number of bread rolls in a package |
| price | The 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
€.
| Template | Description |
|---|---|
default | The default template, matches anything |
ean14_code128 | An EAN-14 embedded in a Code128 with Application Identifier "01" |
ean13_instore | An in-store EAN-13 with embedded data, but no internal checksum |
ean13_instore_chk | An in-store EAN-13 with embedded data and internal checksum |
german_print | German newspapers/magazines with embedded price |
Deposits
If a deposit is to be charged when a product is sold, a deposit product can be assigned to it. This is automatically added to the shopping cart when the product is sold and is correctly taken into account when calculating the price and taxes.
A deposit product is a product of type deposit. It can't be sold by
its own. For example the deposit of bottle might look like:
{
"sku": "38",
"name": "Pfand Bierflasche",
"taxCategory": "normal",
"productType": "deposit",
"isDiscountable": true
}
The deposit is referenced by the product on which it should be applied
through the property depositSKU. For example:
{
"sku": "37",
"name": "Krombacher Pils 0,33l Flasche",
"depositProduct": "38",
// ...
}
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.