Introduction

Welcome to the Developer Portal for the SmartWithFood Product API. This API provides access to a rich database of products, enabling you to seamlessly integrate product-related information into your applications, websites, and services. Whether you are building an e-commerce platform, a logistics solution, or a product comparison site, our API has you covered.

On this developer portal you find the API specifications including a short description of every field, a request example and a response example for every endpoint, and security information, as well as information about the non-functional requirements you can expect from our API is provided. Furthermore, you can find information on how to get started using our API and on who to contact when you are in need of further assistance.

Getting started

Follow the following steps to easily get started with our Product API.

  1. Express your interest in using our API: Contact us via support@smartwithfood.com and we will provide you with all of the information you need to get started with our API.
  2. Explore Documentation: Dive into our detailed API documentation, where you will find information on endpoints, request parameters, response formats, and usage examples.
  3. Integrate and Innovate: Use the API to access product information.

Support

Should you have any questions or need further assistance, please do not hesitate to contact our support team at at support@smartwithfood.com or at https://smartwithfood.atlassian.net/servicedesk/customer/portal/6.

Change Log

The change log in our API developer portal serves as a chronological record detailing updates, enhancements, and modifications to the API, offering developers a transparent history of changes and version releases for improved clarity and understanding.

Version 1.0.2 - Released to STA on 2024-07-16, Released to PRD on 2024-08-06

Modified 'warehouses' request parameter

  • The warehouses array now accepts string or array of strings as items.
  • Impacted endpoints:
    • POST /search
    • POST /facets
    • POST /articles/{id}/alternatives

Version 1.0.1 - Released to STA on 2024-04-02, Released to PRD on 2024-05-28

Added new endpoints

  • DELETE /product/v1/articles/{id}
  • POST /product/v1/articles
  • PUT /product/v1/articles/{id}
  • POST /product/v1/facets
  • Added 'facets' to the POST /search

Added new functionalities to the POST /search

  • sort on measurementUnitPrice
  • sort on isNew

Modified 'article' object

  • Added 'names', 'brands', 'isPrivateLabel', 'labels', 'weightConversionFactor', 'orderUnits' attributes.
  • Impacted endpoints:
    • POST /search
    • GET /articles
    • GET /articles/{id}
    • POST /articles/{id}/alternatives

Modified 'article' promotions object

  • Added 'identifiers' attribute.
  • Impacted endpoints:
    • POST /search
    • GET /articles
    • GET /articles/{id}
    • POST /articles/{id}/alternatives

Modified 'trade item' object

  • Added 'source' attribute.
  • Impacted endpoints:
    • GET /product/v1/tradeitems
    • GET /product/v1/tradeitems/{id}

Version 1.0.2 - Released to STA on 2024-07-16, Released to PRD on 2024-08-06

Modified 'warehouses' request parameter

  • The warehouses array now accepts string or array of strings as items.
  • Impacted endpoints:
    • POST /search
    • POST /facets
    • POST /articles/{id}/alternatives

Version 1.0.1 - Released to STA on 2024-04-02, Released to PRD on 2024-05-28

Added new endpoints

  • DELETE /product/v1/articles/{id}
  • POST /product/v1/articles
  • PUT /product/v1/articles/{id}
  • POST /product/v1/facets
  • Added 'facets' to the POST /search

Added new functionalities to the POST /search

  • sort on measurementUnitPrice
  • sort on isNew

Modified 'article' object

  • Added 'names', 'brands', 'isPrivateLabel', 'labels', 'weightConversionFactor', 'orderUnits' attributes.
  • Impacted endpoints:
    • POST /search
    • GET /articles
    • GET /articles/{id}
    • POST /articles/{id}/alternatives

Modified 'article' promotions object

  • Added 'identifiers' attribute.
  • Impacted endpoints:
    • POST /search
    • GET /articles
    • GET /articles/{id}
    • POST /articles/{id}/alternatives

Modified 'trade item' object

  • Added 'source' attribute.
  • Impacted endpoints:
    • GET /product/v1/tradeitems
    • GET /product/v1/tradeitems/{id}

Non-Functional Requirements

We are committed to providing you with a seamless and reliable experience when integrating our API into your applications. Below you can find the non-functional requirements you can expect from our API.

Performance

Suggest endpoint

  • 99% of requests are expected to have a response time of less than 500 millliseconds.
  • 95% of requests are expected to have a response time of less than 250 milliseconds.

All other endpoints

  • 99% of requests are expected to have a response time of less than 2 seconds.
  • 95% of requests are expected to have a response time of less than 1 second.

Availability

Our API aims for an availability of 99.9%. This translates to approximately 8.5 hours of planned downtime per year.

Throughput

Normal Circumstances

  • Up to 7 requests per second.
  • Up to 120 concurrent requests per minute.
  • Up to 172,000 requests per day.

Peak Circumstances

  • Up to 90 requests per second.
  • Up to 2000 concurrent requests per minute.
  • Up to 100,000 requests per hour.
  • Up to 420,000 requests per day.

API Reference

With this Product API you can access information about articles and trade items. Trade items comprise information associated with the GTIN (Global Trade Item Number) and are therefore not retailer specific. Articles comprise the merged information of a collection of trade items that are sold as one article and are therefore retailer specific. Information that can be consulted on trade item level, but not on article level, includes logistic information and storage information. Information that can be consulted on article level, but not on trade item level, includes prices, promotions and warehouses.

On article level, following methods and endpoints can be used:

  • retrieve a relevance based list of articles, based on search criteria, by using the POST /search;
  • get article suggestions based on user input by using the GET /suggest;
  • retrieve all articles by using the GET /articles;
  • get detailed information about a specific article by providing its unique identifier by using the GET /articles/{id};
  • retrieve alternative articles related to a specific article by using the POST /articles/{id}/alternatives;
  • create an article by using the POST /articles;
  • update an article by using the PUT /articles/{id};
  • delete an article by using the DELETE /articles/{id};
  • retrieve all facets or a selection of facets by using the POST /facets.

On trade item level, following methods and endpoints can be used:

  • retrieve all tradeitems by using the GET /tradeitems;
  • get detailed information about a specific trade item by providing its unique identifier by using the GET /tradeitems/{id};
  • retrieve logistics information related to a specific trade item by using the GET /tradeitems/{id}/logistics;
  • get storage information for a specific trade item by using the GET /tradeitems/{id}/storage.

Check availability

Check if the Product API is available

SecurityNone
Responses
200

Succesful operation.

404

Resource not found.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

get/status
Request samples
Response samples
application/json
{}

Search for articles

Retrieve a relevance based list of articles, based on search criteria

SecurityOAuth2-clientCredentials
Request
header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Request Body schema: application/json
page
number (pageRequest)

The requested page number.

limit
number (limitRequest) <= 100

The number of items returned per page.

channel
string

Unique ID or name of the channel. If no channel is specified, the default facets (brands, lifestyles, allergens, nutriScore, ecoScore, isPrivateLabel, inPromo, userMostBought, prices) will be returned.

Array of objects

List of facets (filters) that will be taken into account in the product search.

q
string

User input of the search bar. Can be any string, GTIN (14 digit) or unique identifier value defined by the tenant.

identifiers
Array of strings [ 0 .. 100 ] items

List of specific identifiers to search on. The identifier value should be specified as 'identifierType:identifier'. Multiple identifiers are handled as an OR operation.

required
Array of Array of strings or strings (warehousesRequest)

List of specific warehouses to search in. The list can contain UUIDs or warehouse identifiers defined by the tenant. Identifiers should be specified as 'identifierType:identifier'. We advise our customers to use identifiers (and not UUIDs) to filter on warehouses.

Items specified within the warehouses array will be treated as OR. This means that the articles returned will be part of one of (at least) the specified items.

brands
Array of strings

List of specific brands to search in.

object (allergensRequest)

Allergens the returned articles should (not) contain.

object (lifestylesRequest)

Lifestyles the returned articles should (not) contain.

object (preferencesRequest)

Preferences the returned articles should (not) contain.

customerId
string (customerIdRequest)

The customerId of the customer that is invoking the service. This is used to look up the Most Frequently Bought information. When a customerId is passed, but no relevant record is found in the Customer resource, the system will silently ignore the customerId.

select
Array of strings

If no select parameter is sent in the request, a default object will be returned. If a select parameter is sent in the request, the fields specified in the select will be returned.

Following fields are part of the default object: id, name, brand, media, ecoScore, nutriScore, servings, amount, amountUnit, isWeightArticle, isPrivateLabel, weightConversionFactor, orderUnits.

Following fields will only be returned if specified in the select parameter: relevance, description, identifiers, barcodes, warehouses, allergens, lifestyles, preferences, promotions, customFields, names, brands, labels.

mediaSizes
Array of strings (mediaSizesRequest)

List of the types of media that will be returned.

sort
Array of strings

The search supports the following values for sorting:

  • price of a specified priceType asc/desc, specified as 'price:priceType:asc' or 'price:priceType:desc'
  • measurementUnitPrice of a specified priceType asc/desc, specified as 'measurementUnitPrice:priceType:asc' or 'measurementUnitPrice:priceType:desc'
  • nutri-score, specified as 'nutriscore:asc' or 'nutriscore:desc'
  • eco-score, specified as 'ecoscore:asc' or 'ecoscore:desc'
  • promotions, specified as 'promotions:asc' or 'promotions:desc'
  • isNew, specificed as 'isNew:asc' or 'isNew:desc'

A combination can be used to search, however every supported sort variable can only be used once. When no sort parameter is entered, the search will default to relevance.

customFields
Array of strings

List of customField values to search in. The customField value should be specified as 'customFieldUUID:customFieldValue' or as 'customFieldName:customFieldValue'.

Responses
200

Succesful operation.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

post/search
Request samples
application/json
{
  • "page": 1,
  • "limit": 25,
  • "channel": "CLP",
  • "facets": [
    ],
  • "q": "kaas met gaten",
  • "identifiers": [
    ],
  • "warehouses": [
    ],
  • "brands": [
    ],
  • "allergens": {
    },
  • "lifestyles": {
    },
  • "preferences": {
    },
  • "customerId": "1234585",
  • "select": [
    ],
  • "mediaSizes": [
    ],
  • "sort": [
    ],
  • "customFields": [
    ]
}
Response samples
application/json
{
  • "total": 30,
  • "pageSize": 25,
  • "totalPages": 2,
  • "articles": [
    ],
  • "facets": [
    ],
  • "ironStock": true
}

Get article suggestions

Get product suggestions based on user input. This endpoint offers real-time suggestions to enhance the user experience and improve search accuracy.

SecurityOAuth2-clientCredentials
Request
query Parameters
q
required
string [ 2 .. 100 ] characters

User input search.

Example: q=ap
limit
number <= 25
Default: 10

Maximum number of results.

Example: limit=10
header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Responses
200

Succesful operation.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

get/suggest
Request samples
Response samples
application/json
{
  • "suggestions": [
    ]
}

Retrieve all articles

Retrieve all articles of a specific warehouse.

SecurityOAuth2-clientCredentials
Request
query Parameters
page
number

The requested page number.

limit
integer <= 100
Default: 25

The number of items that should be returned per page.

select
Array of strings

If no select parameter is sent in the request, a default object will be returned. If a select parameter is sent in the request, the fields specified in the select will be returned.

Following fields are part of the default object: id, name, brand, media, ecoScore, nutriScore, servings, amount, amountUnit, isWeightArticle, isPrivateLabel, weightConversionFactor, orderUnits.

Following fields will only be returned if specified in the select parameter: description, identifiers, barcodes, warehouses, allergens, lifestyles, preferences, promotions, customFields, names, brands, labels.

identifiers
Array of strings

Retrieve articles by identifier.

barcodes
Array of strings

Retrieve articles by barcode.

warehouses
Array of strings

Retrieve articles within specified warehouses.

ids
Array of strings

Retrieve articles by id.

customFields
Array of strings

Retrieve articles by customField value.

header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Responses
200

Succesful operation.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

get/articles
Request samples
Response samples
application/json
{
  • "total": 30,
  • "pageSize": 25,
  • "totalPages": 2,
  • "articles": [
    ]
}

Create a new article

Create a new article.

SecurityOAuth2-clientCredentials
Request
header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Request Body schema: application/json
required
Array of objects

Name of the article.

Array of objects

Name of the article.

Array of objects

Brand of the article.

Array of objects

Brand of the article.

Array of objects

List of media linked to the article.

ecoScore
string

Ecoscore of the article.

Enum: "A" "B" "C" "D" "E"
nutriScore
string

Nutriscore of the article.

Enum: "A" "B" "C" "D" "E" "X"
servings
required
number

The amount of servings the article contains.

amount
required
number
Default: 1

The amount of the article.

amountUnit
string
Default: "piece"

The unit of the amount of the article.

isWeightArticle
required
boolean

Indicates if the article is a weight article or not.

isPrivateLabel
boolean

Indicates if the article belongs to a private label or not.

weightConversionFactor
number

Conversion factor for weight articles. The average weight in g of 1 sales unit.

orderUnits
Array of strings

Indicates if the customer can order the article per piece, per kilogram, or both. If both options are possible, the order shows the order in which the options should be displayed.

Array of objects

Description of the article.

Array of objects

List of identifiers that are specified for the article.

tradeItems
Array of strings

List of barcodes, trade item ids or trade item identifiers that are linked to the article.

warehouses
Array of strings

List of warehouses the article is part of.

Array of objects

List of allergens that are present in the article.

Array of objects

List of lifestyles that are applicable to the article.

labels
Array of strings

List of labels (that are not system labels), that are applicable to the article.

Array of objects or objects

List of custom fields that are applicable to the article.

Responses
201

The article has been created successfully.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

post/articles
Request samples
application/json
{
  • "name": [
    ],
  • "names": [
    ],
  • "brand": [
    ],
  • "brands": [
    ],
  • "media": [
    ],
  • "ecoScore": "A",
  • "nutriScore": "A",
  • "servings": 5,
  • "amount": 250,
  • "amountUnit": "g",
  • "isWeightArticle": true,
  • "isPrivateLabel": true,
  • "weightConversionFactor": 100,
  • "orderUnits": [
    ],
  • "description": [
    ],
  • "identifiers": [
    ],
  • "tradeItems": [
    ],
  • "warehouses": [
    ],
  • "allergens": [
    ],
  • "lifestyles": [
    ],
  • "labels": [
    ],
  • "customFields": [
    ]
}
Response samples
application/json
{
  • "id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
  • "name": {
    },
  • "names": [
    ],
  • "description": {
    },
  • "identifiers": [
    ],
  • "barcodes": [
    ],
  • "brand": {
    },
  • "brands": [
    ],
  • "warehouses": {
    },
  • "media": [],
  • "ecoScore": "A",
  • "nutriScore": "A",
  • "allergens": [
    ],
  • "lifestyles": [
    ],
  • "preferences": [
    ],
  • "servings": 5,
  • "amount": 1,
  • "amountUnit": "piece",
  • "promotions": [
    ],
  • "customFields": [
    ],
  • "isWeightArticle": true,
  • "weightConversionFactor": 100,
  • "orderUnits": [
    ],
  • "isPrivateLabel": true,
  • "labels": [
    ]
}

Retrieve an article by ID

Get detailed information about a specific article by providing its unique identifier.

SecurityOAuth2-clientCredentials
Request
path Parameters
id
required
string

Unique id of the article.

query Parameters
select
Array of strings

If no select parameter is sent in the request, a default object will be returned. If a select parameter is sent in the request, the fields specified in the select will be returned.

Following fields are part of the default object: id, name, brand, media, ecoScore, nutriScore, servings, amount, amountUnit, isWeightArticle, isPrivateLabel, weightConversionFactor, orderUnits.

Following fields will only be returned if specified in the select parameter: description, identifiers, barcodes, warehouses, allergens, lifestyles, preferences, promotions, customFields, names, brands, labels.

warehouses
Array of strings

Get article within specified warehouses. If no warehouse is specified, all warehouses are returned.

header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Responses
200

Succesful operation.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

get/articles/{id}
Request samples
Response samples
application/json
{
  • "id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
  • "name": {
    },
  • "names": [
    ],
  • "description": {
    },
  • "identifiers": [
    ],
  • "barcodes": [
    ],
  • "brand": {
    },
  • "brands": [
    ],
  • "warehouses": {
    },
  • "media": [],
  • "ecoScore": "A",
  • "nutriScore": "A",
  • "allergens": [
    ],
  • "lifestyles": [
    ],
  • "preferences": [
    ],
  • "servings": 5,
  • "amount": 1,
  • "amountUnit": "piece",
  • "promotions": [
    ],
  • "customFields": [
    ],
  • "isWeightArticle": true,
  • "weightConversionFactor": 100,
  • "orderUnits": [
    ],
  • "isPrivateLabel": true,
  • "labels": [
    ]
}

Delete an article

Delete a specific article by providing its unique identifier.

SecurityOAuth2-clientCredentials
Request
path Parameters
id
required
string

Unique id of the article.

header Parameters
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Responses
204

No Content - Delete is processed.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

delete/articles/{id}
Request samples
Response samples
application/json
{
  • "title": "Bad Request",
  • "status": 400,
  • "detail": "Validation Error",
  • "instance": "/productize",
  • "invalidParams": [
    ]
}

Update an existing article

Update an existing article.

SecurityOAuth2-clientCredentials
Request
path Parameters
id
required
string

Unique id of the article.

header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Request Body schema: application/json
required
Array of objects

Name of the article.

Array of objects

Name of the article.

Array of objects

Brand of the article.

Array of objects

Brand of the article.

Array of objects

List of media linked to the article.

ecoScore
string

Ecoscore of the article.

Enum: "A" "B" "C" "D" "E"
nutriScore
string

Nutriscore of the article.

Enum: "A" "B" "C" "D" "E" "X"
servings
required
number

The amount of servings the article contains.

amount
required
number
Default: 1

The amount of the article.

amountUnit
string
Default: "piece"

The unit of the amount of the article.

isWeightArticle
required
boolean

Indicates if the article is a weight article or not.

isPrivateLabel
boolean

Indicates if the article belongs to a private label or not.

weightConversionFactor
number

Conversion factor for weight articles. The average weight in g of 1 sales unit.

orderUnits
Array of strings

Indicates if the customer can order the article per piece, per kilogram, or both. If both options are possible, the order shows the order in which the options should be displayed.

Array of objects

Description of the article.

Array of objects

List of identifiers that are specified for the article.

tradeItems
Array of strings

List of barcodes, trade item ids or trade item identifiers that are linked to the article.

warehouses
Array of strings

List of warehouses the article is part of.

Array of objects

List of allergens that are present in the article.

Array of objects

List of lifestyles that are applicable to the article.

labels
Array of strings

List of labels (that are not system labels), that are applicable to the article.

Array of objects or objects

List of custom fields that are applicable to the article.

Responses
200

The article has been updated successfully.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

put/articles/{id}
Request samples
application/json
{
  • "name": [
    ],
  • "names": [
    ],
  • "brand": [
    ],
  • "brands": [
    ],
  • "media": [
    ],
  • "ecoScore": "A",
  • "nutriScore": "A",
  • "servings": 5,
  • "amount": 250,
  • "amountUnit": "g",
  • "isWeightArticle": true,
  • "isPrivateLabel": true,
  • "weightConversionFactor": 100,
  • "orderUnits": [
    ],
  • "description": [
    ],
  • "identifiers": [
    ],
  • "tradeItems": [
    ],
  • "warehouses": [
    ],
  • "allergens": [
    ],
  • "lifestyles": [
    ],
  • "labels": [
    ],
  • "customFields": [
    ]
}
Response samples
application/json
{
  • "id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
  • "name": {
    },
  • "names": [
    ],
  • "description": {
    },
  • "identifiers": [
    ],
  • "barcodes": [
    ],
  • "brand": {
    },
  • "brands": [
    ],
  • "warehouses": {
    },
  • "media": [],
  • "ecoScore": "A",
  • "nutriScore": "A",
  • "allergens": [
    ],
  • "lifestyles": [
    ],
  • "preferences": [
    ],
  • "servings": 5,
  • "amount": 1,
  • "amountUnit": "piece",
  • "promotions": [
    ],
  • "customFields": [
    ],
  • "isWeightArticle": true,
  • "weightConversionFactor": 100,
  • "orderUnits": [
    ],
  • "isPrivateLabel": true,
  • "labels": [
    ]
}

Retrieve alternative articles

Retrieve alternative articles related to a specific product. This endpoint suggests similar products as alternatives to the one specified.

SecurityOAuth2-clientCredentials
Request
path Parameters
id
required
string

Unique id of the article.

header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Request Body schema: application/json
page
number (pageRequest)

The requested page number.

limit
number (limitRequest) <= 100

The number of items returned per page.

required
Array of Array of strings or strings (warehousesRequest)

List of specific warehouses to search in. The list can contain UUIDs or warehouse identifiers defined by the tenant. Identifiers should be specified as 'identifierType:identifier'. We advise our customers to use identifiers (and not UUIDs) to filter on warehouses.

Items specified within the warehouses array will be treated as OR. This means that the articles returned will be part of one of (at least) the specified items.

object (allergensRequest)

Allergens the returned articles should (not) contain.

object (lifestylesRequest)

Lifestyles the returned articles should (not) contain.

object (preferencesRequest)

Preferences the returned articles should (not) contain.

customerId
string (customerIdRequest)

The customerId of the customer that is invoking the service. This is used to look up the Most Frequently Bought information. When a customerId is passed, but no relevant record is found in the Customer resource, the system will silently ignore the customerId.

select
Array of strings

If no select parameter is sent in the request, a default object will be returned. If a select parameter is sent in the request, the fields specified in the select will be returned.

Following fields are part of the default object: id, name, brand, media, ecoScore, nutriScore, servings, amount, amountUnit, isWeightArticle, isPrivateLabel, weightConversionFactor, orderUnits.

Following fields will only be returned if specified in the select parameter: description, identifiers, barcodes, warehouses, allergens, lifestyles, preferences, promotions, customFields, names, brands, labels.

mediaSizes
Array of strings (mediaSizesRequest)

List of the types of media that will be returned.

Responses
200

Succesful operation.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

post/articles/{id}/alternatives
Request samples
application/json
{
  • "page": 1,
  • "limit": 25,
  • "warehouses": [
    ],
  • "allergens": {
    },
  • "lifestyles": {
    },
  • "preferences": {
    },
  • "customerId": "1234585",
  • "select": [
    ],
  • "mediaSizes": [
    ]
}
Response samples
application/json
{
  • "total": 30,
  • "pageSize": 25,
  • "totalPages": 2,
  • "articles": [
    ]
}

Retrieve facets

Retrieve all facets or a selection of facets.

SecurityOAuth2-clientCredentials
Request
header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Request Body schema: application/json
channel
string

Unique ID or name of the channel. If no channel is specified, the default facets (brands, lifestyles, allergens, nutriScore, ecoScore, isPrivateLabel, inPromo, userMostBought, prices) will be returned.

Array of objects

List of facet filters that will be taken into account.

required
Array of Array of strings or strings (warehousesRequest)

List of specific warehouses to search in. The list can contain UUIDs or warehouse identifiers defined by the tenant. Identifiers should be specified as 'identifierType:identifier'. We advise our customers to use identifiers (and not UUIDs) to filter on warehouses.

Items specified within the warehouses array will be treated as OR. This means that the articles returned will be part of one of (at least) the specified items.

customerId
string (customerIdRequest)

The customerId of the customer that is invoking the service. This is used to look up the Most Frequently Bought information. When a customerId is passed, but no relevant record is found in the Customer resource, the system will silently ignore the customerId.

Responses
200

Succesful operation.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

post/facets
Request samples
application/json
{
  • "channel": "CLP",
  • "facetFilters": [
    ],
  • "warehouses": [
    ],
  • "customerId": "1234585"
}
Response samples
application/json
{
  • "total": 30,
  • "facets": [
    ]
}

Retrieve all trade items

Retrieve all trade items.

SecurityOAuth2-clientCredentials
Request
query Parameters
page
number

The requested page number.

limit
integer <= 100
Default: 25

The number of items that should be returned per page.

select
Array of strings

If no select parameter is sent in the request, a default object will be returned. If a select parameter is sent in the request, the fields specified in the select will be returned.

Following fields are part of the default object: id, source, barcode, name, brand, media, ecoScore, nutriScore, servings, amount, amountUnit, isWeightArticle.

Following fields will only be returned if specified in the select parameter: description, identifiers, customFields.

identifiers
Array of strings

Retrieve trade items by identifier.

barcodes
Array of strings

Retrieve trade items by barcode.

ids
Array of strings

Retrieve trade items by id.

customFields
Array of strings

Retrieve trade items by customField value.

header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Responses
200

Succesful operation.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

get/tradeitems
Request samples
Response samples
application/json
{
  • "total": 30,
  • "pageSize": 25,
  • "totalPages": 2,
  • "tradeItems": [
    ]
}

Retrieve a trade item by ID

Get detailed information about a specific trade item by providing its unique identifier.

SecurityOAuth2-clientCredentials
Request
path Parameters
id
required
string

Unique ID

query Parameters
select
Array of strings

If no select parameter is sent in the request, a default object will be returned. If a select parameter is sent in the request, the fields specified in the select will be returned.

Following fields are part of the default object: id, source, barcode, name, brand, media, ecoScore, nutriScore, servings, amount, amountUnit, isWeightArticle.

Following fields will only be returned if specified in the select parameter: description, identifiers, ingredients, allergens, subAllergens, lifestyles, preferences, nutritionalsPer100Gram, nutritionalsPerPortion, nutritionalsPercentDailyIntake, percentAlcohol, extraTextFields, gln, customFields.

header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Responses
200

Succesful operation.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

get/tradeitems/{id}
Request samples
Response samples
application/json
{
  • "id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
  • "source": "PSS",
  • "barcode": 4008789053381,
  • "name": {
    },
  • "description": {
    },
  • "identifiers": [
    ],
  • "brand": {
    },
  • "media": [],
  • "ecoScore": "A",
  • "nutriScore": "A",
  • "servings": 5,
  • "amount": 1,
  • "amountUnit": "piece",
  • "isWeightArticle": true,
  • "customFields": [
    ],
  • "ingredients": {
    },
  • "allergens": [
    ],
  • "subAllergens": [
    ],
  • "lifestyles": [
    ],
  • "preferences": [
    ],
  • "nutritionalsPer100Gram": [
    ],
  • "nutritionalsPerPortion": [
    ],
  • "nutritionalsPercentDailyIntake": [
    ],
  • "percentAlcohol": 4,
  • "extraTextFields": [
    ],
  • "gln": 4008789053381
}

Retrieve trade item logistics information

Retrieve logistics information related to a specific trade item. This endpoint provides details about shipping, handling, and transportation for the specified product.

SecurityOAuth2-clientCredentials
Request
path Parameters
id
required
string

Unique ID

query Parameters
page
number

The requested page number.

limit
integer <= 100
Default: 25

The number of items that should be returned per page.

select
Array of strings

When given, only return the fields that are listed in this collection.

Possible values are: id, referenceTradeItemId, intrastatCode, isConsumerUnit, isBaseUnit, isDispatchUnit, isVariableUnit, isInvoiceUnit, isOrderableUnit, numberOfUnits, distributorName, layersPerPallet, tradeItemsPerPalletLayer, dimensions, packaging.

header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Responses
200

Succesful operation.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

get/tradeitems/{id}/logistics
Request samples
Response samples
application/json
{
  • "total": 30,
  • "pageSize": 25,
  • "totalPages": 2,
  • "logistics": [
    ]
}

Retrieve trade item storage information

Get storage information for a specific trade item. This endpoint offers insights into how the product should be stored, including temperature requirements and shelf life.

SecurityOAuth2-clientCredentials
Request
path Parameters
id
required
string

Unique ID

query Parameters
page
number

The requested page number.

limit
integer <= 100
Default: 25

The number of items that should be returned per page.

select
Array of strings

When given, only return the fields that are listed in this collection.

Possible values are: id, stage, condition, temperature, lifespan.

header Parameters
Accept-Language
required
string

Internationalization support according to RFC 5646 (ISO 639-1). When multiple languages are given, e.g. nl,en-US;q=0.9,en;q=0.8,nl-NL;q=0.7, the fallback mechanism follows this order.

Example: nl,fr;q=0.9
Authorization
required
string

Authorization header, authorizes the retailer to query the APIs.

Responses
200

Succesful operation.

400

The request could not be understood by the server due to malformed syntax.

401

The caller is not authorized to execute the endpoint.

404

Resource not found.

406

Not Acceptable.

429

The caller is doing too many requests in a small timeframe.

500

The server could not process the request.

get/tradeitems/{id}/storage
Request samples
Response samples
application/json
{
  • "total": 30,
  • "pageSize": 25,
  • "totalPages": 2,
  • "storage": [
    ]
}