Skip to main content
API docs by Redocly

Product Service API (v1)

Download OpenAPI specification:Download

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

Read more about how to use product features like weighable units, code templates, sales restrictions and more.

Products

Manage and access product data.

Get service health

Returns the status of the service.

Authorizations:
bearerAuth
path Parameters
projectID
required
string (ProjectID)

ID of the project

Responses

Response samples

Content type
application/json
{
  • "status": "UP"
}

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

Content type
{
  • "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,
  • "isReturnable": true,
  • "scanMessage": "multipack-2",
  • "codes": [
    ],
  • "additionalAttributes": {
    }
}

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
Default: false

Flag to indicate if the product is currently available in markets.

deleted
boolean
Default: false

Flag to indicate that a product does not exist any longer.

taxCategory
string

Identifier of the tax category

weighByCustomer
boolean
Default: false

Flag, if the product is prepackaged, or the customer has to do weighting by themselves.

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
Default: 0

Indicates necessity of control. -1 no control needed, 1 high control indication. Default is 0, meaning the configured control probability applies.

forceControl
boolean
Default: false

Flag to indicate if a control is necessary.

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
Default: false

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.

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
Default: false

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.

isDiscountable
boolean
Default: false

Flag to indicate if the product should be considered for discounts.

isReturnable
boolean
Default: false

Flag to indicate that the product can be returned.

priceEntryRequired
boolean
Default: false

Flag to indicate if the price of the product should be provided by the customer or the cashier.

fulfillmentType
string

Attribute linking the product with a fulfillment process (i.e. issuing of goods through a vending machine)

object

A string map of additional attributes for special use-cases.

Responses

Request samples

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,
  • "isReturnable": true,
  • "scanMessage": "multipack-2",
  • "codes": [
    ],
  • "additionalAttributes": {
    }
}

Response samples

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,
  • "isReturnable": true,
  • "scanMessage": "multipack-2",
  • "codes": [
    ],
  • "additionalAttributes": {
    }
}

Delete all products

Delete all products in a project.

Authorizations:
bearerAuth
path Parameters
projectID
required
string (ProjectID)

ID of the project

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

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

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,
  • "isReturnable": true,
  • "scanMessage": "multipack-2",
  • "codes": [
    ],
  • "additionalAttributes": {
    }
}

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
Default: false

Flag to indicate if the product is currently available in markets.

deleted
boolean
Default: false

Flag to indicate that a product does not exist any longer.

taxCategory
string

Identifier of the tax category

weighByCustomer
boolean
Default: false

Flag, if the product is prepackaged, or the customer has to do weighting by themselves.

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
Default: 0

Indicates necessity of control. -1 no control needed, 1 high control indication. Default is 0, meaning the configured control probability applies.

forceControl
boolean
Default: false

Flag to indicate if a control is necessary.

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
Default: false

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.

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
Default: false

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.

isDiscountable
boolean
Default: false

Flag to indicate if the product should be considered for discounts.

isReturnable
boolean
Default: false

Flag to indicate that the product can be returned.

priceEntryRequired
boolean
Default: false

Flag to indicate if the price of the product should be provided by the customer or the cashier.

fulfillmentType
string

Attribute linking the product with a fulfillment process (i.e. issuing of goods through a vending machine)

object

A string map of additional attributes for special use-cases.

Responses

Request samples

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,
  • "isReturnable": true,
  • "scanMessage": "multipack-2",
  • "codes": [
    ],
  • "additionalAttributes": {
    }
}

Response samples

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,
  • "isReturnable": true,
  • "scanMessage": "multipack-2",
  • "codes": [
    ],
  • "additionalAttributes": {
    }
}

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

Content type
application/json
{
  • "error": {
    }
}

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

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,
  • "isReturnable": true,
  • "scanMessage": "multipack-2",
  • "codes": [
    ],
  • "additionalAttributes": {
    }
}

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

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/vnd.snabble.product.v2+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
Default: false

Flag to indicate if the product is currently available in markets.

deleted
boolean
Default: false

Flag to indicate that a product does not exist any longer.

taxCategory
string

Identifier of the tax category

weighByCustomer
boolean
Default: false

Flag, if the product is prepackaged, or the customer has to do weighting by themselves.

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
Default: 0

Indicates necessity of control. -1 no control needed, 1 high control indication. Default is 0, meaning the configured control probability applies.

forceControl
boolean
Default: false

Flag to indicate if a control is necessary.

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
Default: false

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.

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
Default: false

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.

isDiscountable
boolean
Default: false

Flag to indicate if the product should be considered for discounts.

isReturnable
boolean
Default: false

Flag to indicate that the product can be returned.

priceEntryRequired
boolean
Default: false

Flag to indicate if the price of the product should be provided by the customer or the cashier.

fulfillmentType
string

Attribute linking the product with a fulfillment process (i.e. issuing of goods through a vending machine)

object

A string map of additional attributes for special use-cases.

Responses

Request samples

Content type
application/vnd.snabble.product.v2+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,
  • "isReturnable": true,
  • "scanMessage": "multipack-2",
  • "codes": [
    ],
  • "additionalAttributes": {
    }
}

Response samples

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

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

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

Content type
application/json
{
  • "value": [
    ]
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

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

Content type
application/x-ndjson
{
  • "op": "delete",
  • "availability": {
    }
}

Response samples

Content type
application/json
{
  • "availability": {
    },
  • "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

Content type
application/json
{
  • "inStock": 240,
  • "created": 122,
  • "updated": 247,
  • "deleted": 8,
  • "count": 240
}

Prices

Batch insert of category pricing

Warning: DRAFT! This endpoint is not yet finalized and may change in the future.

Import an ndjson batch of category pricing objects. Maximal batch size is limited to 20000 items.

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

The SKU of the product for which the pricing applies.

category
required
string

The product category for which the pricings apply.

Array of objects

The prices for the product in the category. These will completely replaces the previous prices in the given category. If no prices are included, the product will no longer have any price in the category.

Responses

Request samples

Content type
application/x-ndjson
{
  • "sku": "1120325205",
  • "category": "default",
  • "prices": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get product pricing for SKU

Warning: DRAFT! This endpoint is not yet finalized and may change in the future.

Get the product pricing for a specific SKU. The response is sorted by category. The prices for a category are sorted by "tier" and then by "validFrom" date (no date for "validFrom" first).

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

Content type
application/json
[
  • {
    }
]