Product API (v1)

Download OpenAPI specification:Download

E-mail: support@smartwithfood.com URL: https://smartwithfood.atlassian.net/servicedesk/customer/portal/6 License: Proprietary License

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.

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.
Explore Documentation: Dive into our detailed API documentation, where you will find information on endpoints, request parameters, response formats, and usage examples.
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..

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

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 Documentation

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.

Search for articles

Retrieve a list of products 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 The requested page number.
limit	number <= 100 Default: 25 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.
	object Facets that will be taken into account in the search.
q	string User input of the search bar. Can be any string or barcode (GTIN).
identifiers	Array of strings List of specific identifiers to search on.
warehouses required	Array of strings List of specific warehouses to search in.
brands	Array of strings List of specific brands to search in.
	object Allergens the returned articles should (not) contain.
	object Lifestyles the returned articles should (not) contain.
	object Preferences the returned articles should (not) contain.
customerId	string 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, isWeighArticle. Following fields will only be returned if specified in the select parameter: relevance, description, identifiers, barcodes, warehouses, allergens, lifestyles, preferences, promotions, customFields.
mediaSizes	Array of strings List of the types of media that will be returned.
sort	Array of strings The search supports the following three fields for sorting: price of a specified priceType asc/desc (if results of only one warehouse are requested) nutriscore ecoscore 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 customFields to search in.

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": "Bio-Planet",
"facets": {"allergens": ["glutenFree"
],
"lifestyles": ["halal"
],
"brands": ["Danone"
],
"nutriScore": ["A"
],
"ecoScore": ["D"
],
"labels": ["categoryId:533"
],
"isPrivateLabel": true,
"inPromo": true,
"userMostBought": true,
"prices": {"min": 5,
"max": 100
}
},
"q": "kaas met gaten",
"identifiers": ["technicalArticleNumber:151545465",
"commercialArticleNumber:7654321"
],
"warehouses": ["38ba2e76-abad-42ff-a648-d5ef8db434b1"
],
"brands": ["Boni Selection",
"Danone"
],
"allergens": {"must": ["gluten",
"38ba2e76-abad-42ff-a648-d5ef8db434b1"
],
"mustNot": ["nuts",
"8eb692d6-5e13-42bc-9cfa-61d6cd8a66d0"
]
},
"lifestyles": {"must": ["veganism",
"38ba2e76-abad-42ff-a648-d5ef8db434b1"
],
"mustNot": ["halal",
"8eb692d6-5e13-42bc-9cfa-61d6cd8a66d0"
]
},
"preferences": {"must": ["bio",
"38ba2e76-abad-42ff-a648-d5ef8db434b1"
],
"mustNot": ["addedSugar",
"8eb692d6-5e13-42bc-9cfa-61d6cd8a66d0"
]
},
"customerId": "1234585",
"select": ["id",
"name",
"brand"
],
"mediaSizes": ["fullFront:100x100",
"small",
"200x200"
],
"sort": ["price:B:asc",
"ecoscore:desc"
],
"customFields": ["38ba2e76-abad-42ff-a648-d5ef8db434b1"
]
}

Response samples

application/json

{"total": 30,
"pageSize": 25,
"totalPages": 2,
"articles": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"relevance": {"name": "override",
"position": 7
},
"name": {"language": "nl",
"text": "Vanille ijs 1kg"
},
"names": [{"language": "nl",
"text": "Vanille ijs",
"type": "longNameDescription"
}
],
"description": {"language": "nl",
"text": "Heerlijk Belgisch vanille ijs."
},
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "commercialArticleNumber",
"identifier": "30542"
}
],
"barcodes": ["04008789053381",
"04008789753380"
],
"brand": {"language": "nl",
"text": "Danone"
},
"brands": [{"brand": {"language": "nl",
"text": "Danone"
},
"order": 1
}
],
"warehouses": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": {"language": "nl",
"text": "Name warehouse"
},
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "branchId",
"identifier": "3873"
}
],
"prices": [{"priceType": "reducedPrice",
"currency": "EUR",
"price": 5.99,
"priceUnit": "kg",
"measurementUnitPrice": 1.45,
"measurementUnit": "l",
"quantity": 5,
"customFlag": "redPrice",
"priceReason": "C",
"referencePrice": 3.45,
"retentionPeriod": 30
}
]
}
],
"media": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"type": "product image full front",
"size": "100x100",
"url": "https://urllocation.com/2376980.jpg",
"title": "Cream cheese on toast.",
"description": "This image shows an example of how to use cream cheese in a recipe."
}
],
"ecoScore": "A",
"nutriScore": "A",
"allergens": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "halal",
"value": "true"
}
],
"preferences": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "chocolate",
"value": "present"
}
],
"servings": 5,
"amount": 1,
"amountUnit": "piece",
"promotions": [{"id": "d5958dda-df78-4fc2-8524-62f8867e0501",
"type": "withEvery",
"maxTimes": 2,
"warehouses": [{"id": "d5958dda-df78-4fc2-8524-62f8867e0501",
"startDate": "2022-07-13T15:34:16+0200",
"endDate": "2023-07-13T15:34:16+0200",
"identifiers": [{ }
]
}
],
"benefits": [{"type": "percentage",
"amount": 10,
"limitUnit": "piece",
"minLimit": 2,
"maxLimit": 15,
"sequence": 1
}
],
"conditions": [{"limitUnit": "piece",
"minLimit": 2,
"maxLimit": 15,
"sequence": 1
}
]
}
],
"isWeightArticle": true,
"customFields": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": false,
"value": "web"
},
{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": true,
"values": ["web",
"mobile"
]
}
]
}
],
"facets": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "categoryId",
"identifier": "342"
}
],
"name": {"language": "en",
"text": "Allergens"
},
"type": "range",
"numberOfArticles": 108,
"order": 3,
"range": {"min": 5,
"max": 100
},
"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	integer <= 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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"suggestions": [{"suggestion": "apple"
}
]
}

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, isWeighArticle. Following fields will only be returned if specified in the select parameter: relevance, description, identifiers, barcodes, warehouses, allergens, lifestyles, preferences, promotions, customFields.
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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"total": 30,
"pageSize": 25,
"totalPages": 2,
"articles": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"relevance": {"name": "override",
"position": 7
},
"name": {"language": "nl",
"text": "Vanille ijs 1kg"
},
"names": [{"language": "nl",
"text": "Vanille ijs",
"type": "longNameDescription"
}
],
"description": {"language": "nl",
"text": "Heerlijk Belgisch vanille ijs."
},
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "commercialArticleNumber",
"identifier": "30542"
}
],
"barcodes": ["04008789053381",
"04008789753380"
],
"brand": {"language": "nl",
"text": "Danone"
},
"brands": [{"brand": {"language": "nl",
"text": "Danone"
},
"order": 1
}
],
"warehouses": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": {"language": "nl",
"text": "Name warehouse"
},
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "branchId",
"identifier": "3873"
}
],
"prices": [{"priceType": "reducedPrice",
"currency": "EUR",
"price": 5.99,
"priceUnit": "kg",
"measurementUnitPrice": 1.45,
"measurementUnit": "l",
"quantity": 5,
"customFlag": "redPrice",
"priceReason": "C",
"referencePrice": 3.45,
"retentionPeriod": 30
}
]
}
],
"media": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"type": "product image full front",
"size": "100x100",
"url": "https://urllocation.com/2376980.jpg",
"title": "Cream cheese on toast.",
"description": "This image shows an example of how to use cream cheese in a recipe."
}
],
"ecoScore": "A",
"nutriScore": "A",
"allergens": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "halal",
"value": "true"
}
],
"preferences": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "chocolate",
"value": "present"
}
],
"servings": 5,
"amount": 1,
"amountUnit": "piece",
"promotions": [{"id": "d5958dda-df78-4fc2-8524-62f8867e0501",
"type": "withEvery",
"maxTimes": 2,
"warehouses": [{"id": "d5958dda-df78-4fc2-8524-62f8867e0501",
"startDate": "2022-07-13T15:34:16+0200",
"endDate": "2023-07-13T15:34:16+0200",
"identifiers": [{ }
]
}
],
"benefits": [{"type": "percentage",
"amount": 10,
"limitUnit": "piece",
"minLimit": 2,
"maxLimit": 15,
"sequence": 1
}
],
"conditions": [{"limitUnit": "piece",
"minLimit": 2,
"maxLimit": 15,
"sequence": 1
}
]
}
],
"isWeightArticle": true,
"customFields": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": false,
"value": "web"
},
{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": true,
"values": ["web",
"mobile"
]
}
]
}
]
}

Create a new article

Create a new article.

SecurityOAuth2-clientCredentials

Request

header Parameters

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.
required	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.
	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 required	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.
	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": [{"language": "nl",
"text": "Vanille ijs 1kg"
}
],
"names": [{"language": "nl",
"text": "Vanille ijs",
"type": "longNameDescription"
}
],
"brand": [{"language": "nl",
"text": "Danone"
}
],
"brands": [{"brand": [{"language": "nl",
"text": "Danone"
}
],
"order": 1
}
],
"media": [{"type": "product image full front",
"size": "100x100",
"language": "nl",
"url": "https://urllocation.com/2376980.jpg",
"title": "Cream cheese on toast.",
"description": "This image shows an example of how to use cream cheese in a recipe."
}
],
"ecoScore": "A",
"nutriScore": "A",
"servings": 5,
"amount": 250,
"amountUnit": "g",
"isWeightArticle": true,
"description": [{"language": "nl",
"text": "Heerlijk Belgisch vanille ijs."
}
],
"identifiers": [{"identifier": "commercialArticleNumber",
"value": 65433
}
],
"tradeItems": ["04008789053381",
"e62aaf74-86b7-4231-8c30-0dca7d5c4e7d"
],
"warehouses": ["bannerCode:CO"
],
"allergens": [{"identifier": "gluten",
"value": "present"
}
],
"lifestyles": [{"identifier": "halal",
"value": "true"
}
],
"customFields": [{"identifier": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"value": "web"
},
{"identifier": "visibleOn",
"values": ["web",
"mobile"
]
}
]
}

Response samples

application/json

{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"name": [{"language": "nl",
"text": "Vanille ijs 1kg"
}
],
"names": [{"language": "nl",
"text": "Vanille ijs",
"type": "longNameDescription"
}
],
"brand": [{"language": "nl",
"text": "Danone"
}
],
"brands": [{"brand": [{"language": "nl",
"text": "Danone"
}
],
"order": 1
}
],
"media": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"type": "product image full front",
"size": "100x100",
"language": "nl",
"url": "https://urllocation.com/2376980.jpg",
"title": "Cream cheese on toast.",
"description": "This image shows an example of how to use cream cheese in a recipe."
}
],
"ecoScore": "A",
"nutriScore": "A",
"servings": 5,
"amount": 200,
"amountUnit": "g",
"isWeightArticle": true,
"description": [{"language": "nl",
"text": "Heerlijk Belgisch vanille ijs."
}
],
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "commercialArticleNumber",
"identifier": "30542"
}
],
"barcodes": ["04008789053381",
"04008789753380"
],
"warehouses": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": [{"language": "nl",
"text": "Name warehouse"
}
],
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "branchId",
"identifier": "3873"
}
]
}
],
"allergens": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "halal",
"value": "true"
}
],
"customFields": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": false,
"value": "web"
},
{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": true,
"values": ["web",
"mobile"
]
}
]
}

Retrieve an article by ID

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

SecurityOAuth2-clientCredentials

Request

path Parameters

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, isWeighArticle.

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

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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"relevance": {"name": "override",
"position": 7
},
"name": {"language": "nl",
"text": "Vanille ijs 1kg"
},
"names": [{"language": "nl",
"text": "Vanille ijs",
"type": "longNameDescription"
}
],
"description": {"language": "nl",
"text": "Heerlijk Belgisch vanille ijs."
},
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "commercialArticleNumber",
"identifier": "30542"
}
],
"barcodes": ["04008789053381",
"04008789753380"
],
"brand": {"language": "nl",
"text": "Danone"
},
"brands": [{"brand": {"language": "nl",
"text": "Danone"
},
"order": 1
}
],
"warehouses": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": {"language": "nl",
"text": "Name warehouse"
},
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "branchId",
"identifier": "3873"
}
],
"prices": [{"priceType": "reducedPrice",
"currency": "EUR",
"price": 5.99,
"priceUnit": "kg",
"measurementUnitPrice": 1.45,
"measurementUnit": "l",
"quantity": 5,
"customFlag": "redPrice",
"priceReason": "C",
"referencePrice": 3.45,
"retentionPeriod": 30
}
]
}
],
"media": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"type": "product image full front",
"size": "100x100",
"url": "https://urllocation.com/2376980.jpg",
"title": "Cream cheese on toast.",
"description": "This image shows an example of how to use cream cheese in a recipe."
}
],
"ecoScore": "A",
"nutriScore": "A",
"allergens": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "halal",
"value": "true"
}
],
"preferences": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "chocolate",
"value": "present"
}
],
"servings": 5,
"amount": 1,
"amountUnit": "piece",
"promotions": [{"id": "d5958dda-df78-4fc2-8524-62f8867e0501",
"type": "withEvery",
"maxTimes": 2,
"warehouses": [{"id": "d5958dda-df78-4fc2-8524-62f8867e0501",
"startDate": "2022-07-13T15:34:16+0200",
"endDate": "2023-07-13T15:34:16+0200",
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "branchId",
"identifier": "3873"
}
]
}
],
"benefits": [{"type": "percentage",
"amount": 10,
"limitUnit": "piece",
"minLimit": 2,
"maxLimit": 15,
"sequence": 1
}
],
"conditions": [{"limitUnit": "piece",
"minLimit": 2,
"maxLimit": 15,
"sequence": 1
}
]
}
],
"isWeightArticle": true,
"customFields": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": false,
"value": "web"
},
{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": true,
"values": ["web",
"mobile"
]
}
]
}

Delete an article

Delete a specific article by providing its unique identifier.

SecurityOAuth2-clientCredentials

Request

path Parameters

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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"title": "Bad Request",
"status": 400,
"detail": "Validation Error",
"instance": "/articles",
"invalidParams": [{"in": "query",
"name": "limit",
"reason": "limit must not be greater than 100",
"value": 101
}
]
}

Update an existing article

Update an existing article.

SecurityOAuth2-clientCredentials

Request

path Parameters

required

string

Unique id of the article.

header Parameters

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.
required	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.
	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 required	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.
	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": [{"language": "nl",
"text": "Vanille ijs 1kg"
}
],
"names": [{"language": "nl",
"text": "Vanille ijs",
"type": "longNameDescription"
}
],
"brand": [{"language": "nl",
"text": "Danone"
}
],
"brands": [{"brand": [{"language": "nl",
"text": "Danone"
}
],
"order": 1
}
],
"media": [{"type": "product image full front",
"size": "100x100",
"language": "nl",
"url": "https://urllocation.com/2376980.jpg",
"title": "Cream cheese on toast.",
"description": "This image shows an example of how to use cream cheese in a recipe."
}
],
"ecoScore": "A",
"nutriScore": "A",
"servings": 5,
"amount": 250,
"amountUnit": "g",
"isWeightArticle": true,
"description": [{"language": "nl",
"text": "Heerlijk Belgisch vanille ijs."
}
],
"identifiers": [{"identifier": "commercialArticleNumber",
"value": 65433
}
],
"tradeItems": ["04008789053381",
"e62aaf74-86b7-4231-8c30-0dca7d5c4e7d"
],
"warehouses": ["bannerCode:CO"
],
"allergens": [{"identifier": "gluten",
"value": "present"
}
],
"lifestyles": [{"identifier": "halal",
"value": "true"
}
],
"customFields": [{"identifier": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"value": "web"
},
{"identifier": "visibleOn",
"values": ["web",
"mobile"
]
}
]
}

Response samples

application/json

{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"name": [{"language": "nl",
"text": "Vanille ijs 1kg"
}
],
"names": [{"language": "nl",
"text": "Vanille ijs",
"type": "longNameDescription"
}
],
"brand": [{"language": "nl",
"text": "Danone"
}
],
"brands": [{"brand": [{"language": "nl",
"text": "Danone"
}
],
"order": 1
}
],
"media": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"type": "product image full front",
"size": "100x100",
"language": "nl",
"url": "https://urllocation.com/2376980.jpg",
"title": "Cream cheese on toast.",
"description": "This image shows an example of how to use cream cheese in a recipe."
}
],
"ecoScore": "A",
"nutriScore": "A",
"servings": 5,
"amount": 200,
"amountUnit": "g",
"isWeightArticle": true,
"description": [{"language": "nl",
"text": "Heerlijk Belgisch vanille ijs."
}
],
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "commercialArticleNumber",
"identifier": "30542"
}
],
"barcodes": ["04008789053381",
"04008789753380"
],
"warehouses": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": [{"language": "nl",
"text": "Name warehouse"
}
],
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "branchId",
"identifier": "3873"
}
]
}
],
"allergens": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "halal",
"value": "true"
}
],
"customFields": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": false,
"value": "web"
},
{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": true,
"values": ["web",
"mobile"
]
}
]
}

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

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 The requested page number.
limit	number <= 100 Default: 25 The number of items returned per page.
warehouses required	Array of strings List of specific warehouses to search in.
	object Allergens the returned articles should (not) contain.
	object Lifestyles the returned articles should (not) contain.
	object Preferences the returned articles should (not) contain.
customerId	string 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, isWeighArticle. Following fields will only be returned if specified in the select parameter: relevance, description, identifiers, barcodes, warehouses, allergens, lifestyles, preferences, promotions, customFields.
mediaSizes	Array of strings 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": ["38ba2e76-abad-42ff-a648-d5ef8db434b1"
],
"allergens": {"must": ["gluten",
"38ba2e76-abad-42ff-a648-d5ef8db434b1"
],
"mustNot": ["nuts",
"8eb692d6-5e13-42bc-9cfa-61d6cd8a66d0"
]
},
"lifestyles": {"must": ["veganism",
"38ba2e76-abad-42ff-a648-d5ef8db434b1"
],
"mustNot": ["halal",
"8eb692d6-5e13-42bc-9cfa-61d6cd8a66d0"
]
},
"preferences": {"must": ["bio",
"38ba2e76-abad-42ff-a648-d5ef8db434b1"
],
"mustNot": ["addedSugar",
"8eb692d6-5e13-42bc-9cfa-61d6cd8a66d0"
]
},
"customerId": "1234585",
"select": ["id",
"name",
"brand"
],
"mediaSizes": ["fullFront:100x100",
"small",
"200x200"
]
}

Response samples

application/json

{"total": 30,
"pageSize": 25,
"totalPages": 2,
"articles": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"relevance": {"name": "override",
"position": 7
},
"name": {"language": "nl",
"text": "Vanille ijs 1kg"
},
"names": [{"language": "nl",
"text": "Vanille ijs",
"type": "longNameDescription"
}
],
"description": {"language": "nl",
"text": "Heerlijk Belgisch vanille ijs."
},
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "commercialArticleNumber",
"identifier": "30542"
}
],
"barcodes": ["04008789053381",
"04008789753380"
],
"brand": {"language": "nl",
"text": "Danone"
},
"brands": [{"brand": {"language": "nl",
"text": "Danone"
},
"order": 1
}
],
"warehouses": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": {"language": "nl",
"text": "Name warehouse"
},
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": "branchId",
"identifier": "3873"
}
],
"prices": [{"priceType": "reducedPrice",
"currency": "EUR",
"price": 5.99,
"priceUnit": "kg",
"measurementUnitPrice": 1.45,
"measurementUnit": "l",
"quantity": 5,
"customFlag": "redPrice",
"priceReason": "C",
"referencePrice": 3.45,
"retentionPeriod": 30
}
]
}
],
"media": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"type": "product image full front",
"size": "100x100",
"url": "https://urllocation.com/2376980.jpg",
"title": "Cream cheese on toast.",
"description": "This image shows an example of how to use cream cheese in a recipe."
}
],
"ecoScore": "A",
"nutriScore": "A",
"allergens": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "halal",
"value": "true"
}
],
"preferences": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "chocolate",
"value": "present"
}
],
"servings": 5,
"amount": 1,
"amountUnit": "piece",
"promotions": [{"id": "d5958dda-df78-4fc2-8524-62f8867e0501",
"type": "withEvery",
"maxTimes": 2,
"warehouses": [{"id": "d5958dda-df78-4fc2-8524-62f8867e0501",
"startDate": "2022-07-13T15:34:16+0200",
"endDate": "2023-07-13T15:34:16+0200",
"identifiers": [{ }
]
}
],
"benefits": [{"type": "percentage",
"amount": 10,
"limitUnit": "piece",
"minLimit": 2,
"maxLimit": 15,
"sequence": 1
}
],
"conditions": [{"limitUnit": "piece",
"minLimit": 2,
"maxLimit": 15,
"sequence": 1
}
]
}
],
"isWeightArticle": true,
"customFields": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": false,
"value": "web"
},
{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": true,
"values": ["web",
"mobile"
]
}
]
}
]
}

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, articleId, barcode, name, brand, media, ecoScore, nutriScore, servings, amount, amountUnit, isWeighArticle. 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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"total": 30,
"pageSize": 25,
"totalPages": 2,
"tradeItems": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"barcode": 4008789053381,
"name": {"language": "nl",
"text": "Leerdammer kaas met gaten"
},
"description": {"language": "nl",
"text": "Heerlijke kaas met gaten."
},
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": null,
"identifier": null
}
],
"brand": {"language": "nl",
"text": "Danone"
},
"media": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"type": "small",
"language": "nl",
"url": "https://static.colruytgroup.com/wcsstore/ColruytB2CCAS/JPG/JPG/200x310/std.lang.all/69/80/asset-2376980.jpg",
"title": "Cream cheese on toast.",
"description": "This image shows an example of how to use cream cheese in a recipe."
}
],
"ecoScore": "A",
"nutriScore": "A",
"servings": 5,
"amount": 1,
"amountUnit": "piece",
"isWeightArticle": true,
"customFields": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": false,
"value": "web"
},
{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": true,
"values": ["web",
"mobile"
]
}
]
}
]
}

Retrieve a trade item by ID

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

SecurityOAuth2-clientCredentials

Request

path Parameters

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, articleId, barcode, name, brand, media, ecoScore, nutriScore, servings, amount, amountUnit, isWeighArticle.

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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"barcode": 4008789053381,
"name": {"language": "nl",
"text": "Leerdammer kaas met gaten"
},
"description": {"language": "nl",
"text": "Heerlijke kaas met gaten."
},
"identifiers": [{"id": "e62aaf74-86b7-4231-8c30-0dca7d5c4e7d",
"type": null,
"identifier": null
}
],
"ingredients": {"language": "nl",
"text": "Water, perenmoes (42%), suiker, antioxidant (ascorbinezuur). Vruchtgehalte: 42%."
},
"brand": {"language": "nl",
"text": "Danone"
},
"media": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"type": "small",
"language": "nl",
"url": "https://static.colruytgroup.com/wcsstore/ColruytB2CCAS/JPG/JPG/200x310/std.lang.all/69/80/asset-2376980.jpg",
"title": "Cream cheese on toast.",
"description": "This image shows an example of how to use cream cheese in a recipe."
}
],
"ecoScore": "A",
"nutriScore": "A",
"allergens": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "gluten",
"value": "present"
}
],
"subAllergens": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "pecan nut",
"value": "present"
}
],
"lifestyles": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "halal",
"value": "true"
}
],
"preferences": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"name": "chocolate",
"value": "present"
}
],
"servings": 5,
"amount": 1,
"amountUnit": "piece",
"nutritionalsPer100Gram": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": {"language": "nl",
"text": "Suiker"
},
"amount": {"value": 543254.4567,
"unit": "SUGAR",
"factor": 0.239
},
"portion": {"value": 40,
"unit": "g",
"factor": 0.239
},
"conversion": {"value": 1.38501,
"unit": "g",
"factor": 0.000001
},
"createdAt": "2019-08-24T14:15:22Z",
"modifiedAt": "2019-08-24T14:15:22Z"
}
],
"nutritionalsPerPortion": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": {"language": "nl",
"text": "Suiker"
},
"amount": {"value": 543254.4567,
"unit": "SUGAR",
"factor": 0.239
},
"portion": {"value": 40,
"unit": "g",
"factor": 0.239
},
"conversion": {"value": 1.38501,
"unit": "g",
"factor": 0.000001
},
"createdAt": "2019-08-24T14:15:22Z",
"modifiedAt": "2019-08-24T14:15:22Z"
}
],
"nutritionalsPercentDailyIntake": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": {"language": "nl",
"text": "Suiker"
},
"amount": {"value": 543254.4567,
"unit": "SUGAR",
"factor": 0.239
},
"portion": {"value": 40,
"unit": "g",
"factor": 0.239
},
"conversion": {"value": 1.38501,
"unit": "g",
"factor": 0.000001
},
"createdAt": "2019-08-24T14:15:22Z",
"modifiedAt": "2019-08-24T14:15:22Z"
}
],
"percentAlcohol": 4,
"extraTextFields": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"type": "regulatedName",
"value": {"language": "nl",
"text": "Oikos Greek Yoghurt"
}
}
],
"gln": 4008789053381,
"isWeightArticle": true,
"customFields": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": false,
"value": "web"
},
{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": "select",
"name": "visibleOn",
"description": "Specifies if content is visible on web and/or mobile",
"createdAt": "2022-07-13T15:34:16+0200",
"modifiedAt": "2022-07-13T15:34:16+0200",
"multipleOptions": true,
"values": ["web",
"mobile"
]
}
]
}

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

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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"total": 30,
"pageSize": 25,
"totalPages": 2,
"logistics": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"referenceTradeItemId": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"intrastatCode": 21039090,
"isConsumerUnit": true,
"isBaseUnit": true,
"isDispatchUnit": true,
"isVariableUnit": true,
"isInvoiceUnit": true,
"isOrderableUnit": true,
"numberOfUnits": 6,
"distributorName": "PepsiCo BeLux BVBA/SPRL",
"layersPerPallet": 30,
"tradeItemsPerPalletLayer": 12,
"dimensions": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"name": {"language": "en",
"text": "netWeight"
},
"value": 24,
"unit": "kg"
}
],
"packaging": {"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"type": {"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"name": {"language": "en",
"text": "pallet1200x1000mm"
},
"description": {"language": "en",
"text": "Flat pallet with dimensions of 1200 x 1000 mm  ISO 6780 ISO 2 Pallet, EUR 2 Pallet."
},
"gs1Code": 12
},
"dimensions": [{"id": "762C947E-0B17-4AC7-92DF-798D868576DB",
"name": {"language": "en",
"text": "height"
},
"value": 1638,
"unit": "mm"
}
],
"materials": [{"id": "762C947E-0B17-4AC7-92DF-798D868576DB",
"name": {"language": "en",
"text": "hardwood"
},
"description": {"language": "en",
"text": "A general term referring to any variety of broad-leaved, deciduous trees, and the wood from those trees. The term has nothing to do with the actual hardness of the wood; some hardwoods are softer than certain softwood (evergreen) species."
},
"gs1Code": "WOOD_HARDWOOD",
"isRecyclable": true
}
]
}
}
]
}

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

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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"total": 30,
"pageSize": 25,
"totalPages": 2,
"storage": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"stage": {"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"name": {"language": "en",
"text": "afterPreparation"
},
"gs1Code": "STORAGE_HANDLING",
"description": {"language": "en",
"text": "Trade item is being stored or handled."
}
},
"condition": {"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"name": {"language": "en",
"text": "deep_frozen"
},
"gs1Code": "DEEP_FROZEN",
"description": {"language": "en",
"text": "The product is stored inside of a deep freezer (not in a refrigerator) at a temperature which maintains a deep-frozen state, but is not above -18C/0F. Please refer to local regulations for temperature range."
}
},
"temperature": {"min": -18,
"max": -7,
"unit": "°C"
},
"lifespan": {"value": 4,
"unit": "years"
}
}
]
}

Product API (v1)

Introduction

Getting started

Support

Non-Functional Requirements

Performance

Availability

Throughput

API Documentation

Search for articles

header Parameters

Request Body schema: application/json

Get article suggestions

query Parameters

header Parameters

Retrieve all articles

query Parameters

header Parameters

Create a new article

header Parameters

Request Body schema: application/json

Retrieve an article by ID

path Parameters

query Parameters

header Parameters

Delete an article

path Parameters

header Parameters

Update an existing article

path Parameters

header Parameters

Request Body schema: application/json

Retrieve alternative articles

path Parameters

header Parameters

Request Body schema: application/json

Retrieve facets

header Parameters

Request Body schema: application/json

Retrieve all trade items

query Parameters

header Parameters

Retrieve a trade item by ID

path Parameters

query Parameters

header Parameters

Retrieve trade item logistics information

path Parameters

query Parameters

header Parameters

Retrieve trade item storage information

path Parameters

query Parameters

header Parameters