Best Practices

Always start with Offers and Orders

In terms of complexity the Orders process is the easiest to understand and implement, followed by Offers. Managing Content 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

  • Become familiar with the most crucial sales processes

  • Quickly start making a profit and benefit from the efficiency improvements, so that you can prove that the API integration is a success

  • Use this success to justify investing in a Content API integration.

It is possible to connect to the entire API at once, but we recommend doing it in this order.

Be aware that the API is asynchronous

With the exception of some endpoints, all non-GET requests to our API are asynchronous. This means that all PUT, POST and DELETE requests are always ordered 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:

  • Shipping an order item (with Track and Trace)

  • Updating stock

  • Updating 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 reused 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 rate limits 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.

This video explains our token policy and what do if you are IP blocked:

Only update offers 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.

Stay within the rate limits

Every endpoint in the API has its own rate limit. These rate limits are designed with the following factors in mind:

  • Allowing you to make use of the API to fully support your sales processes as quickly as possible

  • Protecting the bol.com landscape from abuse and overloading

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

There are two ways to determine the rate limit for the endpoint you need:

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

  • A complete list of the current rate limits can be found on the rate limits 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 rate limit to reset.

Use the Postman suite for testing

We have shared a Postman library that contains all API endpoints including examples in both JSON and XML (V3 and v5 only). You can find the suite here.

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

Pause your bol.com shop when testing 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 wish 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 the shop is paused all your API requests are treated with low priority. They could take longer to process than usual.