The product content section of the API can be used to send your product content towards bol.com. It will eventually fully replace the Content FTP option. We recommend new connections to only use the Content API.
The API Reference for developers can be found at: https://api.bol.com/retailer/public/redoc/v4#tag/Content
Logical process flow
Shown below is simplified version of the flow you follow to add or update new content on bol.com.
Step 1 – Get the Datamodel
The bol.com Datamodel is an XML file that contains all bol.com Product Classifications. This file is updated weekly and we recommend importing this file often to stay up to date.
A product Classification is the most basic level to classify a product. It does describe the location of the product in a store or category. It will list products at the level of e.g.:
In this example, a sneaker, based on it’s other characteristics can end up in either the fashion store or the sports store, or both.
The datamodel contains all 4000+ classifications available on the bol.com platform. They are listed in alphabetic order and are not grouped by store or category.
Per classification the datamodel will show which attributes are applicable to that classification. It will also show if the attribute is required and if it allows any value or if a value must be selected from a predefined list.
Use the datamodel to find the correct classification for you product, determine the required attributes and values you wish to send.
per attribute the datamodel will show it’s enrichmentLevel value. This determines if the attribute is required to be entered.
enrichmentLevel 0 and 1 are required. Without this the product will not be shown on the webshop
enrichmentLevel 2 and 3 are optional.
Step 2 – Post your content using the API
Based on the classification you have selected from the datamodel you can build your JSON/XML payload to send to the Content API.
You select only the attributes that you want to send and use these in your request.
An example of a content API POST request:
Step 2.1 Choose language
Every upload must first announce the language it will be sending it’s content in. Currently we support Dutch (
''nl-BE''), Wallonia (
''fr-BE'') and French (
''fr''). Check the API Reference for more information.
Step 2.2 Choose Internal Reference
The Internal Reference is the unique product identifier which you have to supply for each product. This could be the product EAN or your own custom product identifier. This value is not shown on the site, but is used to link specific feedback to the uploaded products. Failing to provide an Internal Reference will result in an error.
Step 2.3 Send basic information
For all content added we need at least 1 piece of information in order to process the data:
Are you sending content for an entirely new product for the bol.com platform? In that case it is also required that you provide the classification when sending content for the first time.
If you are updating content for existing items, you do not need to send any classification information.
You can specific the classification by setting the Product Classification attribute. The value you provide is listed as the <name> of the <productType> in the Datamodel.
For example, if you wish to add a cardgame you would provide:
Step 2.4 Build the rest of your response
After providing the very basics, you can now list all the other attributes that you intend to send. Each attribute is send as an id, value combination.
The id in the API corresponds to the <name> in the datamodel.
Please note that all the <name> elements in the datamodel are always in English, but the value you provide must always be in the language you specified.
For example, when adding a cardgame you could provide the amount of players.
The datamodel will show:
The corresponding API request will look like:
In this case you are updating an existing cardgame. If this had been a new cardgame, a classification would also have needed to be provided. (in addition to all other enrichtmentLevel 0 and 1 attributes!)
Use POST https://api.bol.com/retailer/content/product to send us your content.
2.5 Send us content in bulk.
It is possible to send us content in bulk, please make sure to use a different internal reference for every distinct product.
2.6 Send multivalue attributes
For some attributes we accept more than 1 value, you can add several values within this one attribute while sending new content. This is for example used when sending several images describing different views of your product.
Step 3 – Verify your POST
Like all requests in the bol.com Retailer API, your content POST is also added to our queue. After posting you will receive a process-status response.
Use the process-status endpoint to check the status of your request. At first it will always have status PENDING. This will change after it was successfully processed, which can take up to several minutes.
If the upload is successful you will receive SUCCESS status and an entityId.
Step 4 – Get your Validation report and fix any problems
For a successful upload of content you can retrieve a report detailed all successful added attributes but also all the problems we encountered. You can use this report to fix any reported problems and send a new request.
Use the Get Validation Request endpoint and the entityID you received to fetch the report
In this example:
In case of a problem you would see:
The validation report consists of:
- Validation information for all uploaded products: was your uploaded content accepted by bol.com?
- Currently do not validate images, video’s and PDFs. We only check if the field is an URL.
- Validation status on product level (see table 1 below)
- Error codes for all errors (see table 2 below)
Note: The validation report is available for 28 days. After this period, you cannot retrieve the validation report anymore.
4.1 Validation Report product-level status types with their meaning
|VALIDATED_OK||The product has passed the validation with zero errors|
|VALIDATED_WITH_ATTRIBUTE_FAILURES||The product has passed the validation and the attributes that have failures won’t be processed|
|REJECTED||The product is rejected and no validation errors are given|
|REJECTED_WITH_ATTRIBUTE_FAILURES||The product is rejected and validation errors are given back|
4.2 The following error codes exist in the validation report.
|1000||whole product rejected|
|2000||unknown attribute error|
|2001||invalid multiple values|
|2002||attribute id does not exist|
|2003||invalid numeric text|
|2016||Invalid values were supplied (empty string or invalid HTML)|
|2017||No values were supplied for the attribute|