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 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.
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
The process status tutorial videos give an introduction for using 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.