Changes to Retailer API release cycle and migration information
As previously announced, there will be a significant change to the release cycle of the Retailer API and the Advertising API. As of 2024, bol will no longer schedule full API releases every 6 months. Instead, version updates will be applied to resources if and when needed. With this change we aim to reduce the number of required migrations for partners, as well as increase the number of valuable features that will be launched in the future.
Versioning per resource
The Retailer API is divided into a number of different resources, such as the Offers resource and the Product Content resource. Each of these resources will be kept up to date by having its own version starting at v10 for the Retailer API and v11 for the Advertising API. The benefit of this approach is that users only have to upgrade resources if there is something changing in their implementation. Additionally, a resource will remain stable as long as no breaking changes are introduced.
Major changes require a version upgrade
Resources will be updated to a new version as soon as a breaking change is introduced to one or more of the endpoints in that resource.
Minor changes to existing version
Minor changes to one or more endpoints that will not break existing implementations, can be introduced at any time. Under normal circumstances these releases will not require any downtime. Examples of minor changes include:
- Adding new optional fields to a request body, provided this doesn’t change the endpoint behavior.
- Adding new optional query parameters to the request, provided they don’t change endpoint behavior and have well-defined default values.
Announcing new versions
New versions will only be released if breaking changes are introduced to a certain resource. These planned version updates will then be posted on our Developers Portal at least 14 days before release. The developer portal gives the option of following our RSS feed to keep track of any changes or known issues.
Minor changes that will not break existing implementations will not require an upgrade to a resource version. However, these improvements will be posted on the Developers Portal.
Deprecated versions
Whenever a new version of a particular resource is released, the resource it supersedes is marked as deprecated and will be scheduled for removal after a minimum support period of 12 months, in accordance with our Terms of Service. The support period for deprecated resources in the Advertising API is currently set at 3 months. During this Deprecation stage, the Retailer API will be fully supported and all endpoints will remain active until their final removal.
Migration
To use the benefits of the new release cycle, it is necessary to migrate to the latest version, the Retailer API v10. Users of v7/v8 have to migrate before May 1st 2024. Users of v9 have to migrate before November 1st 2024.
Please note that users of the Advertiser API might need to migrate to v11 earlier based on their batch. Please see this page for more information.
To help you with the migration, we created this overview of breaking changes between v7/v8/v9 and v10.
In depth migration guides can be found here:
Questions?