bol.com Retailer API migration guide V3 to v4

Version 4 of the Retailer API introduces some significant improvements to bol.com’s partner developer tools. We recommend upgrading from V3 to take advantage of the enhanced designs and features in the new API.

The API lifecycle schedule can be found here. Please ensure that you migrate from V3 before it is removed on 1 October 2021.

New features in v4

Adding product information: serve your product content via the Retailer API.
Insights in assortment and sales: retrieve insights in your offer performance and expected sales forecast.
Process status in bulk: retrieve multiple process statuses in one single request.
Subscribe for relevant events (beta): subscribe to specific events from bol.com.
Retrieve retail price information (beta): retrieve price information for EANs.
Retrieve your unpublished offers (beta): retrieve your offers that are not yet published.
New shipping label flow: purchase shipping labels from bol.com, including through the new Verzenden Via Bol.com service.

New features are only available in v4. For details regarding the implementation of these features, refer to the documentation. This migration guide does not cover the implementation of new features.

Changed resources

To guide you through the right steps and take important changes into account, you can use this migration guide to migrate from V3 to v4. Any changes in this guide are compared to v3.

We endeavored to align resources though a list of predefined conventions. Examples of these conventions are:

Date or DateTime type description included in field names, for example orderPlacedDateTime
Dates and DateTimes are in ISO 8601 format
Country codes are in ISO 3166-1 format
ENUM values are uppercase
Primary identifiers use the <object>Id nomenclature, for example orderId, inboundId, shipmentId.

Aside from these conventions we have made changes to several resources to align the models and make them more logical:

Table 1. Table of changed resources
Resource	Impact
Commissions	Low (4 changes)
Inbounds	High (29 changes)
Insights	Low (2 changes)
Inventory	Low (5 changes)
Invoices	Low (2 changes)
Offers	Medium (10 changes)
Orders	High (52 changes)
Reductions	Endpoints removed
Returns	High (36 changes)
Shipments	High (47 changes)
Shipping labels	Endpoint removed
Transports	No changes