Best Practices

  • Always start with Offers & Orders

  • Our API is a-synchronous

  • Recycle your security-token until it expires

  • Offers can only be updated by using their primary identifier

  • Mind the ratelimits

  • Use our Postman suite

  • Pauze your bol.com shop to test your API connection

This page contains best practices related to the entire API. We have separate guides for specific subjects, like order process.

Always start with Offers & Orders

In terms of complexity the orders process is the most easiest to understand and implement, followed by the offers process. Content however is far more complex and requires at least twice the amount of work. For any new Integration-project we recommend to always start with offers and orders. This allows you to:

  • Get familiar with our API

  • Get the Authentication set up properly

  • Covers the most crucial sales processes

  • Allows you to quickly start making a profit and benefit from the efficiency improvements and prove the API integration is a success

  • Use this success to justify investing in a Content API Integration

While of course connecting to our entire API in 1 go is always an option, we do recommend doing it and the aforementioned order.

Our API is Asynchronous

Except for some endpoints, all non-GET requests to our API are asynchronous. This means that all PUT, POST and DELETE requests are always put on our queue first before being processed.

This in turn means that the 200 OK that you receive after sending us a request only means that we received your request. It does not mean we were able to process your request. In this 200 OK we also provide a process-status-id.

The API has a specific endpoint that allows you to check the status of your request. This is the only way to determine if your request was processed successfully by bol.com.

We recommend to always implement the process-status for at least your most crucial updates such as:

  • Ship an order item (with Track&trace)

  • Update stock

  • Update price

Recycle your security-token until it expires

When authenticating with our API you will receive a token that you can use for your API requests. This token has a certain lifetime and can be re-used as often as you like within this lifetime.

Please make sure to fully use this token. Do not request a new token before the current one has expired.

The ratelimits on requesting a new token are very strict due to security measures that are in place to prevent abuse. If you exceed these limits you will be banned from the entire platform for a limited period of time.

Offers can only be updated by using their primary identifier

All your offers at bol.com receive a unique offerId. After creating an offer you can use the process-status to determine the assigned offerId. Updating stock, price, deliverycode or deleting the offer all require you to use this offerId. Offers cannot be updated by their EAN.

Mind the ratelimits

Every endpoint in the API has it’s own ratelimit. These ratelimits are designed with the following in mind:

  • Allow you to make use of the API to fully support your sales processes and be able to do so quickly.

  • Protect the bol.com landscape from abuse and overloading.

  • Share the available resources between all bol.com merchant partners

There are 2 ways to determine the ratelimit for the endpoint you need:

  • In every response we add header information that list how many requests you can still perform within a certain timeframe.

  • A complete list of the ratelimits at our ratelimits page.

Header Value Description

X-RateLimit-Limit

20

The total limit currently effective for this endpoint, 20 requests can be made in total

X-RateLimit-Reset

1539261914

The time in milliseconds since the EPOCH in GMT after which the current limit will be reset

X-RateLimit-Remaining

19

The time in milliseconds since the EPOCH in GMT after which the current limit will be reset

We recommend implementing this header information into your code. When nearing the end of your quota you can implement a delay to allow for the ratelimit to reset.

Use our Postman suite

We have shared a Postman library that contains all API endpoints including examples in both JSON and XML. You can find the suite using the menu on the left.

Make use of these libraries to browse through the API, get familiar with the endpoints and formats and also to confirm that the responses you get in your code match the ones you see in postman.

Pause your bol.com shop to test your API connection

There is no sandbox environment for the bol.com Retailer API.

You can use the demo-environment to get a preview of all requests including examples.

If you with to test your API connection before going live you can temporarily pause your shop on bol.com. Your entire account will still work and the API will still be active, but consumers will not be able to order from you.

Please note that while “paused” all your API requests are treated with low-priority. They could take longer to process than usual.