Open API migration guide

bol.com webshop data now available in Retailer API

As bol.com we are constantly looking at ways to improve our retailing partner experience. As part of this track, we have explored to expose bol.com webshop related data to our retailing partners. Something that has been requested many times. For those who would like to start using this data, we would like to recommend the regular documentation of the bol.com Retailer API V9 release. The documentation will guide you through the process in a way you are familiar with.

Use of Open API versus Retailer API

We acknowledge that many of you have been using the bol.com Open API (also known as the 'Affiliate API') to retrieve webshop-related data. While Open API provides access to valuable information, it was not originally designed for this purpose and has resulted in challenges such as onboarding difficulties and different conventions than our Retailer API.

After years of providing support, we have determined that Open API no longer meets our internal quality standards. Therefore, the Open API will be phased out for our Retailing partners. To address this, we have prioritized the development of new endpoints in Retailer API to replace the data that was offered through Open API. With input from our partners, we have enhanced features and streamlined data to provide a better user experience.

Introduction

We understand that migrating to a new API can be challenging, so we have created this page to make the process as smooth as possible. The new endpoints are designed to align with the conventions and principles of Retailer API, and thus have a different setup compared to Open API. To assist you, we have included an endpoint mapping, object mapping, and a FAQ section to provide an overview of the key changes.

If you encounter any obstacles along the way, our frequently asked questions section below and our Technical Support team (openapi-migratie@bol.com) are here to help. Our experts will guide you through the migration process and provide assistance if needed. We value your feedback, so if you have any suggestions for improvement, please let us know.

Please note that this guide assumes a basic understanding of Retailer API. If you are new to Retailer API or have not worked with it recently, we recommend reviewing the conventions, the rate limits, and the lifecycle process to ensure a successful migration.

We are here to support you every step of the way. Good luck with your migration!

Endpoint mapping

Four endpoints of Open API are particularly interesting for our retailing partners, based on our data analysis and research.
Please note that GET /catalog/v4/recommendations and GET /catalog/v4/relatedproducts hardly have any usage and we therefore decided not to invest in a substitute. 

The following sections provide details regarding the endpoint mapping. They also include examples of common requests made to Open API and their corresponding replacement requests for Retailer API.

Some notes regarding these examples:

• the IDs of products in Open API requests and Retailer API requests are different because Retailer API works based on EAN.
• the search and lists endpoints have many query parameters. Some are not included in this example.

Products endpoint

Example Open API request: GET /catalog/v4/products/1001004011182718?includeattributes=true&offers=bestoffer&country=NL

Example Retailer API requests:

• product data: GET /retailer/content/catalog-products/9780137081073
• offer data: GET /retailer/products/9780137081073/offers?country-code=NL&best-offer-only=true

Offers endpoint

Example Open API request: GET /catalog/v4/products/1001004011182718?includeattributes=true&offers=bestoffer&country=NL

Example Retailer API requests:

• product data: GET /retailer/content/catalog-products/9780137081073
• offer data: GET /retailer/products/9780137081073/offers?country-code=NL&best-offer-only=true

Search endpoint

Example Open API request: GET /catalog/v4/search?q=clean%20coder&dataoutput
=products&offers=bestoffer&sort=relevance&includeattributes=false&country=NL

Example Retailer API requests:

• search results, products: POST /retailer/insights/product-list with body
{
"countryCode": "NL",
"searchTerm": "clean coder",
"sort": "RELEVANCE"
}
• offer data, per product: GET /retailer/products/{ean}/offers?country-code=NL&best-offer-only=true

List endpoint

Example Open API request: GET /catalog/v4/lists?ids=40409&dataoutput=
products&sort=popularity&includeattributes=false&country=NL

Example Retailer API requests:

• search results, products: POST /retailer/insights/product-list with body
{
"countryCode": "NL",
"categoryId": "40409",
"sort": "POPULARITY"
}
• offer data, per product: GET /retailer/products/{ean}/offers?country-code=NL&best-offer-only=true

Object mapping

For each endpoint within Open API, we described the current fields and where to find the data in Retailer API.

The field names in Open API are from the JSON responses. The XML responses will be similar, but often different in how they are cased (lowerCamelCase vs UpperCamelCase).

Note: we would like to add additional markup to the text in the tables for improved readability, but this website's CMS does not allow it.

Products object

The following table shows the attributes of a Product object, which can be returned by the products, search and lists endpoints of Open API.

* Regarding 'entityGroups' field: on this page, you will find a list of party types and corresponding roles.

Offer data object

The following table shows the attributes of an OfferData object, which can be returned by the products, offers, search and lists endpoints of Open API.

Seller object

The following table shows the attributes of a Seller object, which can be returned by the products, offers, search and lists endpoints of Open API.

Note: the table describes the complete object with all its attributes. The products endpoint in Open API returns less attributes.
Note: the XML encoded response includes "recentReviewCounts" as "allReviewsCounts".

Frequently Asked Questions

General

1. Why is support ending for Open API?
   The core application behind Open API is at the end of its lifecycle and it no longer meets our quality norms for our retailing partners. Fixing the issues would require a substantial effort and we would rather direct that effort to Retailer API, which has a bright future ahead of it.
2. We will need to use multiple endpoints where we previously used to only use one. Can you include more data in an endpoint response?
   In Retailer API we offer 'lean' endpoints that expose a specific type of data. This aligns with our product vision of keeping endpoints lean, fast and only offering data in one place. Retailer API provides lean endpoints to prevent serving data that might not be used by the API consumer. This ensures requested data actually gets used. Therefore, we won't add data of one endpoint into the response of another. However, if you feel some important data is missing, please reach out to our Technical Support via: openapi-migratie@bol.com.
3. What happens if we keep using Open API?
   We strongly encourage partners to change their integrations and start using Retailer API. Using Open API will no longer be supported for our Retailing partners. Retailer API is fully supported, and future improvement will only be made in Retailer API.
4. Can we use both API's at the same time, to test or run shadow mode?
   Yes, you can use both API's side by side. However, for applications like repricers that produce a high volume of requests, we ask that you use a subset of products to run these side by side with. Because of the load on our services we do ask that you try to keep this period of running side by side short and that you stop using Open API as soon as you can confidently do so.
5. When will the new endpoints go GA (General Available)?
   Please keep an eye on the Open API migration page for the latest information on the timelines.
6. Is it safe to implement the v9 BETA endpoints?
   Yes, the endpoints are tested, supported and run in our production environment, serving production data. We believe the endpoints are ready to be implemented by partners. The endpoints have BETA status to indicate something may change to further improve the endpoints, based on your feedback.
   For example, Product Placement recently got an improvement where we added hierarchy to the category data.

Rate limits

1. The rate limits on the new endpoints in Retailer API seem too low for our use cases. Can you please raise the rate limits?
   With rate limits, we try to find the optimal balance between consumer needs and load on our backend services. Due to the different set-up of Open API and Retailer API, it is challenging to forecast the exact load per endpoint. In the coming months, we will monitor the usage and adjust the rate limits where needed and feasible.
2. What happens if the rate limits of the new endpoints in Retailer API are too low for our use cases?
   We would appreciate it if you could contact our Technical Support via openapi-migratie@bol.com to explain your use cases and needs. This is valuable input for our capacity planning.

Data in responses

1. Why is the total number of results for a search or a category not included in the product-list response?
   In Retailer API the convention is not to expose total counts or data that can be calculated from the response with simple math. This keeps the endpoints lean and provides a consistent developer experience.
2. Why are no product details included in the product-list response?
   Retailer API aims to provide lean endpoints that are fast and offer data in one place. Product data can be retrieved by using the 'Get catalog product details by EAN' endpoint.
3. I’m missing data that used to be in Open API, where can I retrieve it?
   The object mapping tables on this page provide detailed information on where data can be found. In some cases, the data is no longer available. If you feel some important data is missing, please reach out to us using one of the methods provided below, so we can investigate adding this data to the API.
4. Can we get responses in XML, just like in Open API?
   Retailer API does not provide XML encoding. Other differences to note are that endpoints in Open API support the "format" query parameter to request a response in JSON or XML, as well as an "Accept" header to indicate the same. The default encoding in Open API is JSON. Retailer API provides responses in JSON and the encoding is requested through providing an "Accept" header (see documentation).

Search & Lists

1. Where is the replacement for the Lists endpoint of Open API?
   The Search and Lists endpoints of Open API are using the same underlying service to get the results. And since both return the same type of data (a list of products), we decided to combine the two and offer one endpoint: 'Get product list'. This new endpoint uses the same internal source as the endpoints in Open API and should therefore provide the same results. The Product List endpoint can be used by itself for most simple use cases. For more advanced use cases, the Product List endpoint requires IDs that can be retrieved by using the Product Placement and Product List Filters endpoints.
2. How do I know which Category ID I should use?
   The Category IDs can be found based on product, using the 'Get product placement' endpoint, or based on a search term using the 'Get list filters' endpoint. The 'Get list filters' endpoint can also be used to find subcategories for a category.

How can I ask a different question?

You can always get in contact with our Technical Support via: openapi-migratie@bol.com. Experts will guide you in your migration steps and it will give us the chance to update our documentation based on your feedback.

Version history