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.

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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"type": "https://swf-recipeapi-v1.redoc.ly/#tag/API-Reference",
"title": "Not Found",
"status": 404,
"detail": "The requested path was not found",
"instance": "/recipe/v1/productise"
}

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": [[{"identifier": "allergens",
"keys": ["lactoseFree",
"glutenFree"
]
},
{"identifier": "lifestyles",
"keys": ["veganism",
"halal"
]
},
{"identifier": "categories",
"keys": ["554",
"223"
]
},
{"identifier": "brands",
"keys": ["boni",
"danone"
]
},
{"identifier": "nutriScore",
"keys": ["A",
"B"
]
},
{"identifier": "ecoScore",
"keys": ["A",
"B"
]
},
{"identifier": "isPrivateLabel"
},
{"identifier": "inPromo"
},
{"identifier": "inAction"
},
{"identifier": "userMostBought"
},
{"identifier": "labels",
"keys": ["isNew",
"inSeason",
"addedSugars",
"sugarFree",
"lowSugar"
]
},
{"identifier": "prices",
"range": {"min": 0,
"max": 20
}
}
]
],
"q": "kaas met gaten",
"identifiers": ["technicalArticleNumber:1515454",
"commercialArticleNumber:7654321"
],
"warehouses": ["branchId:7863",
["bannerCode:CO",
"countryCode:BE",
"branchType:HANDOVER_POINT"
],
["bannerCode:2B",
"sellingPartner:CLPBE"
]
],
"brands": ["Boni Selection",
"Danone"
],
"allergens": {"must": ["gluten",
"ACADA715-3842-11EA-BA36-6E1C41F2F90A"
],
"mustNot": ["nuts",
"ACFA978A-3842-11EA-BA36-6E1C41F2F90A"
]
},
"lifestyles": {"must": ["veganism",
"0A06EFC4-3843-11EA-BA36-6E1C41F2F90A"
],
"mustNot": ["halal",
"09F0E916-3843-11EA-BA36-6E1C41F2F90A"
]
},
"preferences": {"must": ["garlic",
"8E695CB0-A945-11EC-BBC8-995808538238"
],
"mustNot": ["preservatives",
"856FD8A0-A945-11EC-BBC8-995808538238"
]
},
"customerId": "1234585",
"select": ["id",
"name",
"brand"
],
"mediaSizes": ["small",
"100x100"
],
"sort": ["price:B:asc",
"measurementUnitPrice:B:desc",
"ecoscore:desc",
"nutriscore:asc",
"promotions:asc",
"isNew:desc"
],
"customFields": ["6B563C81-995D-4B4F-AF3D-00654EF5353F:87654",
"replacementArticle:87654"
]
}

Response samples

application/json

{"total": 30,
"pageSize": 25,
"totalPages": 2,
"articles": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"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": "T4A4CCP2-25BD-48C6-8382-782296AEB6PA",
"type": "branchId",
"identifier": "3873"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782296AEB6PA",
"type": "countryCode",
"identifier": "BE"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "sellingPartner",
"identifier": "CLP"
},
{"id": "Z4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "type",
"identifier": "HANDOVER_POINT"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6PA",
"type": "bannerCode",
"identifier": "CO"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6RC",
"type": "commerceCode",
"identifier": "COLRUYT"
}
],
"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": "100x100",
"language": "nl",
"url": "https://static.colruytgroup.com/wcsstore/ColruytB2CCAS/JPG/JPG/200x310/std.lang.all/69/80/asset-2376980.jpg",
"title": "Celery chopping",
"description": "This image shows how to chop celery."
}
],
"ecoScore": "A",
"nutriScore": "A",
"allergens": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "halal",
"value": "true"
}
],
"preferences": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"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
}
]
}
],
"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"
]
}
],
"isWeightArticle": true,
"weightConversionFactor": 100,
"orderUnits": ["P",
"Kg",
"P, Kg"
],
"isPrivateLabel": true,
"labels": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"identifier": "Gambia",
"name": {"language": "nl",
"text": "Gambia"
},
"channels": ["CLP"
]
}
],
"relevance": {"name": "exactMatch",
"position": 1
}
}
],
"facets": [[{"identifier": "categories",
"type": "select",
"count": 1056,
"order": 0,
"children": [{"key": "543",
"name": {"text": "Conserven",
"language": "nl"
},
"count": 565,
"order": 0,
"children": [{"key": "654",
"name": {"text": "Groentenconserven",
"language": "nl"
},
"count": 342,
"order": 0,
"children": [{"key": "322",
"name": {"text": "Olijven",
"language": "nl"
},
"count": 13,
"order": 0,
"children": [ ]
}
]
},
{"key": "655",
"name": {"text": "Fruitconserven",
"language": "ml"
},
"type": "select",
"count": 156,
"order": 1,
"children": [{"key": "873",
"name": {"text": "Ananas",
"language": "nl"
},
"count": 12,
"order": 1,
"children": [ ]
}
]
}
]
}
]
},
{"identifier": "allergens",
"type": "select",
"order": 1,
"children": [{"key": "lactoseFree",
"count": 321,
"order": 0,
"children": [ ]
}
]
},
{"identifier": "lifestyles",
"type": "select",
"order": 2,
"children": [{"key": "halal",
"count": 281,
"order": 0,
"children": [ ]
}
]
},
{"identifier": "brands",
"type": "select",
"order": 3,
"children": [{"key": "danone",
"name": {"text": "Danone",
"language": "nl"
},
"count": 432,
"order": 0,
"children": [ ]
}
]
},
{"identifier": "nutriScore",
"type": "select",
"order": 4,
"children": [{"key": "A",
"count": 125,
"order": 0,
"children": [ ]
},
{"key": "B",
"count": 126,
"order": 1,
"children": [ ]
}
]
},
{"identifier": "ecoScore",
"type": "select",
"order": 5,
"children": [{"key": "A",
"count": 129,
"order": 0,
"children": [ ]
}
]
},
{"identifier": "isPrivateLabel",
"count": 87,
"order": 6,
"children": [ ]
},
{"identifier": "inPromo",
"count": 234,
"order": 7,
"children": [ ]
},
{"identifier": "userMostBought",
"count": 345,
"order": 8,
"children": [ ]
},
{"identifier": "inAction",
"count": 342,
"order": 9,
"children": [ ]
},
{"identifier": "labels",
"count": 654,
"order": 10,
"children": [{"key": "isNew",
"count": 281,
"order": 0,
"children": [ ]
},
{"key": "inSeason",
"count": 281,
"order": 0,
"children": [ ]
},
{"key": "addedSugars",
"count": 281,
"order": 0,
"children": [ ]
},
{"key": "sugarFree",
"count": 281,
"order": 0,
"children": [ ]
},
{"key": "lowSugar",
"count": 281,
"order": 0,
"children": [ ]
}
]
},
{"identifier": "prices",
"type": "range",
"order": 11,
"range": {"min": 5,
"max": 6
},
"children": [ ]
}
]
],
"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

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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"total": 30,
"pageSize": 25,
"totalPages": 2,
"articles": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"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": "T4A4CCP2-25BD-48C6-8382-782296AEB6PA",
"type": "branchId",
"identifier": "3873"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782296AEB6PA",
"type": "countryCode",
"identifier": "BE"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "sellingPartner",
"identifier": "CLP"
},
{"id": "Z4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "type",
"identifier": "HANDOVER_POINT"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6PA",
"type": "bannerCode",
"identifier": "CO"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6RC",
"type": "commerceCode",
"identifier": "COLRUYT"
}
],
"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": "100x100",
"language": "nl",
"url": "https://static.colruytgroup.com/wcsstore/ColruytB2CCAS/JPG/JPG/200x310/std.lang.all/69/80/asset-2376980.jpg",
"title": "Celery chopping",
"description": "This image shows how to chop celery."
}
],
"ecoScore": "A",
"nutriScore": "A",
"allergens": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "halal",
"value": "true"
}
],
"preferences": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"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
}
]
}
],
"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"
]
}
],
"isWeightArticle": true,
"weightConversionFactor": 100,
"orderUnits": ["P",
"Kg",
"P, Kg"
],
"isPrivateLabel": true,
"labels": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"identifier": "Gambia",
"name": {"language": "nl",
"text": "Gambia"
},
"channels": ["CLP"
]
}
]
}
]
}

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": [{"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,
"isPrivateLabel": true,
"weightConversionFactor": 100,
"orderUnits": ["P",
"Kg",
"P, Kg"
],
"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"
}
],
"labels": [["countriesOfOrigin:Gambia",
"inSeason"
]
],
"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"
}
],
"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": "T4A4CCP2-25BD-48C6-8382-782296AEB6PA",
"type": "branchId",
"identifier": "3873"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782296AEB6PA",
"type": "countryCode",
"identifier": "BE"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "sellingPartner",
"identifier": "CLP"
},
{"id": "Z4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "type",
"identifier": "HANDOVER_POINT"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6PA",
"type": "bannerCode",
"identifier": "CO"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6RC",
"type": "commerceCode",
"identifier": "COLRUYT"
}
],
"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": "100x100",
"language": "nl",
"url": "https://static.colruytgroup.com/wcsstore/ColruytB2CCAS/JPG/JPG/200x310/std.lang.all/69/80/asset-2376980.jpg",
"title": "Celery chopping",
"description": "This image shows how to chop celery."
}
],
"ecoScore": "A",
"nutriScore": "A",
"allergens": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "halal",
"value": "true"
}
],
"preferences": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"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
}
]
}
],
"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"
]
}
],
"isWeightArticle": true,
"weightConversionFactor": 100,
"orderUnits": ["P",
"Kg",
"P, Kg"
],
"isPrivateLabel": true,
"labels": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"identifier": "Gambia",
"name": {"language": "nl",
"text": "Gambia"
},
"channels": ["CLP"
]
}
]
}

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

curl
Node.js
JavaScript
PHP
Python

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"
}
],
"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": "T4A4CCP2-25BD-48C6-8382-782296AEB6PA",
"type": "branchId",
"identifier": "3873"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782296AEB6PA",
"type": "countryCode",
"identifier": "BE"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "sellingPartner",
"identifier": "CLP"
},
{"id": "Z4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "type",
"identifier": "HANDOVER_POINT"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6PA",
"type": "bannerCode",
"identifier": "CO"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6RC",
"type": "commerceCode",
"identifier": "COLRUYT"
}
],
"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": "100x100",
"language": "nl",
"url": "https://static.colruytgroup.com/wcsstore/ColruytB2CCAS/JPG/JPG/200x310/std.lang.all/69/80/asset-2376980.jpg",
"title": "Celery chopping",
"description": "This image shows how to chop celery."
}
],
"ecoScore": "A",
"nutriScore": "A",
"allergens": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "halal",
"value": "true"
}
],
"preferences": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"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
}
]
}
],
"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"
]
}
],
"isWeightArticle": true,
"weightConversionFactor": 100,
"orderUnits": ["P",
"Kg",
"P, Kg"
],
"isPrivateLabel": true,
"labels": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"identifier": "Gambia",
"name": {"language": "nl",
"text": "Gambia"
},
"channels": ["CLP"
]
}
]
}

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

{"type": "https://swf-recipeapi-v1.redoc.ly/#tag/API-Reference",
"title": "Bad Request",
"status": 400,
"detail": "Validation Error",
"instance": "/productize",
"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

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": [{"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,
"isPrivateLabel": true,
"weightConversionFactor": 100,
"orderUnits": ["P",
"Kg",
"P, Kg"
],
"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"
}
],
"labels": [["countriesOfOrigin:Gambia",
"inSeason"
]
],
"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"
}
],
"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": "T4A4CCP2-25BD-48C6-8382-782296AEB6PA",
"type": "branchId",
"identifier": "3873"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782296AEB6PA",
"type": "countryCode",
"identifier": "BE"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "sellingPartner",
"identifier": "CLP"
},
{"id": "Z4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "type",
"identifier": "HANDOVER_POINT"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6PA",
"type": "bannerCode",
"identifier": "CO"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6RC",
"type": "commerceCode",
"identifier": "COLRUYT"
}
],
"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": "100x100",
"language": "nl",
"url": "https://static.colruytgroup.com/wcsstore/ColruytB2CCAS/JPG/JPG/200x310/std.lang.all/69/80/asset-2376980.jpg",
"title": "Celery chopping",
"description": "This image shows how to chop celery."
}
],
"ecoScore": "A",
"nutriScore": "A",
"allergens": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "halal",
"value": "true"
}
],
"preferences": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"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
}
]
}
],
"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"
]
}
],
"isWeightArticle": true,
"weightConversionFactor": 100,
"orderUnits": ["P",
"Kg",
"P, Kg"
],
"isPrivateLabel": true,
"labels": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"identifier": "Gambia",
"name": {"language": "nl",
"text": "Gambia"
},
"channels": ["CLP"
]
}
]
}

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 (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": ["branchId:7863",
["bannerCode:CO",
"countryCode:BE",
"branchType:HANDOVER_POINT"
],
["bannerCode:2B",
"sellingPartner:CLPBE"
]
],
"allergens": {"must": ["gluten",
"ACADA715-3842-11EA-BA36-6E1C41F2F90A"
],
"mustNot": ["nuts",
"ACFA978A-3842-11EA-BA36-6E1C41F2F90A"
]
},
"lifestyles": {"must": ["veganism",
"0A06EFC4-3843-11EA-BA36-6E1C41F2F90A"
],
"mustNot": ["halal",
"09F0E916-3843-11EA-BA36-6E1C41F2F90A"
]
},
"preferences": {"must": ["garlic",
"8E695CB0-A945-11EC-BBC8-995808538238"
],
"mustNot": ["preservatives",
"856FD8A0-A945-11EC-BBC8-995808538238"
]
},
"customerId": "1234585",
"select": ["id",
"name",
"brand"
],
"mediaSizes": ["small",
"100x100"
]
}

Response samples

application/json

{"total": 30,
"pageSize": 25,
"totalPages": 2,
"articles": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"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": "T4A4CCP2-25BD-48C6-8382-782296AEB6PA",
"type": "branchId",
"identifier": "3873"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782296AEB6PA",
"type": "countryCode",
"identifier": "BE"
},
{"id": "B4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "sellingPartner",
"identifier": "CLP"
},
{"id": "Z4A4CCA2-25BD-48C6-8382-782236AEB6DA",
"type": "type",
"identifier": "HANDOVER_POINT"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6PA",
"type": "bannerCode",
"identifier": "CO"
},
{"id": "B4A4CCA2-65BD-48C6-8382-782296AEB6RC",
"type": "commerceCode",
"identifier": "COLRUYT"
}
],
"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": "100x100",
"language": "nl",
"url": "https://static.colruytgroup.com/wcsstore/ColruytB2CCAS/JPG/JPG/200x310/std.lang.all/69/80/asset-2376980.jpg",
"title": "Celery chopping",
"description": "This image shows how to chop celery."
}
],
"ecoScore": "A",
"nutriScore": "A",
"allergens": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "gluten",
"value": "present"
}
],
"lifestyles": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"name": "halal",
"value": "true"
}
],
"preferences": [{"id": "e1b044ad-8998-45cd-962b-b0fd8ca7cc0d",
"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
}
]
}
],
"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"
]
}
],
"isWeightArticle": true,
"weightConversionFactor": 100,
"orderUnits": ["P",
"Kg",
"P, Kg"
],
"isPrivateLabel": true,
"labels": [{"id": "61c5bf4b-fbcf-48d0-ae21-34c9bb3151a6",
"identifier": "Gambia",
"name": {"language": "nl",
"text": "Gambia"
},
"channels": ["CLP"
]
}
]
}
]
}

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. The allergen facet returns those articles for which the allergen value is 'notPresent' or 'probablyNotPresent'. The lifestyle facet returns those articles for which the lifestyle value is 'true'.
	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

Response samples

application/json

{"total": 30,
"facets": [[{"identifier": "categories",
"type": "select",
"count": 1056,
"order": 0,
"children": [{"key": "543",
"name": {"text": "Conserven",
"language": "nl"
},
"count": 565,
"order": 0,
"children": [{"key": "654",
"name": {"text": "Groentenconserven",
"language": "nl"
},
"count": 342,
"order": 0,
"children": [{"key": "322",
"name": {"text": "Olijven",
"language": "nl"
},
"count": 13,
"order": 0,
"children": [ ]
}
]
},
{"key": "655",
"name": {"text": "Fruitconserven",
"language": "ml"
},
"type": "select",
"count": 156,
"order": 1,
"children": [{"key": "873",
"name": {"text": "Ananas",
"language": "nl"
},
"count": 12,
"order": 1,
"children": [ ]
}
]
}
]
}
]
},
{"identifier": "allergens",
"type": "select",
"order": 1,
"children": [{"key": "lactoseFree",
"count": 321,
"order": 0,
"children": [ ]
}
]
},
{"identifier": "lifestyles",
"type": "select",
"order": 2,
"children": [{"key": "halal",
"count": 281,
"order": 0,
"children": [ ]
}
]
},
{"identifier": "brands",
"type": "select",
"order": 3,
"children": [{"key": "danone",
"name": {"text": "Danone",
"language": "nl"
},
"count": 432,
"order": 0,
"children": [ ]
}
]
},
{"identifier": "nutriScore",
"type": "select",
"order": 4,
"children": [{"key": "A",
"count": 125,
"order": 0,
"children": [ ]
},
{"key": "B",
"count": 126,
"order": 1,
"children": [ ]
}
]
},
{"identifier": "ecoScore",
"type": "select",
"order": 5,
"children": [{"key": "A",
"count": 129,
"order": 0,
"children": [ ]
}
]
},
{"identifier": "isPrivateLabel",
"count": 87,
"order": 6,
"children": [ ]
},
{"identifier": "inPromo",
"count": 234,
"order": 7,
"children": [ ]
},
{"identifier": "userMostBought",
"count": 345,
"order": 8,
"children": [ ]
},
{"identifier": "inAction",
"count": 342,
"order": 9,
"children": [ ]
},
{"identifier": "labels",
"count": 654,
"order": 10,
"children": [{"key": "isNew",
"count": 281,
"order": 0,
"children": [ ]
},
{"key": "inSeason",
"count": 281,
"order": 0,
"children": [ ]
},
{"key": "addedSugars",
"count": 281,
"order": 0,
"children": [ ]
},
{"key": "sugarFree",
"count": 281,
"order": 0,
"children": [ ]
},
{"key": "lowSugar",
"count": 281,
"order": 0,
"children": [ ]
}
]
},
{"identifier": "prices",
"type": "range",
"order": 11,
"range": {"min": 5,
"max": 6
},
"children": [ ]
}
]
]
}

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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"total": 30,
"pageSize": 25,
"totalPages": 2,
"tradeItems": [{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"source": "PSS",
"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, 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

curl
Node.js
JavaScript
PHP
Python

Response samples

application/json

{"id": "38ba2e76-abad-42ff-a648-d5ef8db434b1",
"source": "PSS",
"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"
]
}
],
"ingredients": {"language": "nl",
"text": "Water, perenmoes (42%), suiker, antioxidant (ascorbinezuur). Vruchtgehalte: 42%."
},
"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"
}
],
"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
}

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",
"barcode": "04008789053381",
"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": null,
"text": null
},
"value": 1638,
"unit": "mm"
}
],
"materials": [{"id": "762C947E-0B17-4AC7-92DF-798D868576DB",
"name": {"language": null,
"text": null
},
"description": {"language": null,
"text": null
},
"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"
}
}
]
}