Best Practices
This page contains some recommendations about best practices when using our API.
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 many endpoints are asynchronous
Many non-GET requests to our API are processed asynchronously: the request is placed on our queue first and processed afterwards. This pattern is common across the Retailer API, but it is not universal — some endpoints respond synchronously and complete the operation within the request itself. Newer APIs and versions (such as the Offer API v11) introduce more synchronous endpoints, so always check whether the specific endpoint you are calling is asynchronous.
For an asynchronous endpoint, the success response (200 OK) only confirms that we received your request — it does not mean the request was processed successfully. This response includes a processStatusId.
To determine whether an asynchronous request actually succeeded, use the process status endpoint — this is the only reliable way to confirm the outcome. You can tell whether an endpoint is asynchronous from its reference (Redoc) documentation, which returns a process status response.
We recommend always implementing the process status check for at least your most crucial asynchronous updates, such as:
-
Shipping an order item (with Track and Trace)
-
Updating stock
-
Updating price
The process status tutorial videos give an introduction to the asynchronous model.
Parse CSV file type reports dynamically
To ensure your integration remains effective and can handle future updates without disruption, it is essential to prepare for the addition of new fields in CSV file type reports. This practice enhances the data provided, enabling better insights and usability.
Guidelines for Parsing CSV Reports
Dynamic parsing: Ensure your system is designed to dynamically parse CSV reports. Rather than relying on a fixed schema, your parser should be capable of handling varying numbers of columns and interpreting them based on headers.
Header driven parsing: Always use the headers of the CSV files to identify and process fields. This approach ensures that even if new fields are added, your system can recognize and handle them appropriately without requiring immediate updates to your parsing logic.
Robust error handling: Implement robust error handling to manage unexpected fields or missing data. This will help maintain the stability of your integration in case of future changes.
Regular updates: Stay informed about changes via our developer portal or release notes for the version you are currently integrated to. Regularly review these sources and update your parsing logic as needed to quickly adapt to new fields and data structures.
Testing: Regularly test your CSV parsing implementation against the latest reports. This proactive approach will help identify any issues early and ensure seamless integration.
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 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 landscape from abuse and overloading
-
Sharing the available resources between all bol 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. The total amount of requests that can be made are twenty. |
X-RateLimit-Remaining |
19 |
The amount of requests remaining until the current limit is reset. |
X-RateLimit-Reset |
Any value between 1-60 (seconds). |
The time remaining in seconds for the current rate limit to 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 JSON. You can find the v10 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 shop when testing your API connection
There is no sandbox environment for the bol 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.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.
Use the latest version
Ensuring that you utilize the latest version of the Retailer API is crucial for staying up-to-date with the latest features, enhancements, and security updates.The Retailer API follows a versioning system where each resource may have its own version.Here are some best practices for using the latest version based on the versioning per resource:
Regularly check for updates
Keep an eye on BOL Partner Platform and Developer Platform or subscribe to the BOL Developers Feed to receive notifications about new version releases for each resource.Updates are typically posted at least 14 days before release, allowing you ample time to prepare for any changes.
Understand deprecation policies
Deprecated versions are marked for removal after a specified support period, usually 12 months.Ensure that you migrate to the latest version within this timeframe to avoid disruption to your operations.