bol.com Retailer API migration guide v3 to v4

At bol.com we are working hard to help our partners grow their business every day. One way how we do that is by innovating on partner tooling functionalities in our seller dashboard, but also in the Retailer API channel. Our latest innovations are that significant that we introduce a new version, Retailer API v4.

New features in version 4

Adding product information; provide your product content through 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 yourself for specific events that will be pushed towards you from bol.com.
Retrieve retail price information (beta); retrieve price information for a specific EAN.
Retrieve your unpublished offers (beta); retrieve your offers that are not yet published.
New shipping label flow; purchase shipping labels from bol.com, including the new 'Verzenden via bol.com' proposition.

Be advised that that new features are introduced in version 4 only. For details regarding the implementation of this features, please take a look at the (functional) documentation. Implementation of new features is not in scope of this migration guide.

Changed resources

To guide you through the right steps and take important changes into account, you can use this migration guide to migrate from version 3 to version 4. Changes mentioned are compared to the v3 version.

We put a lot of effort in aligning all resources by holding them against a list of pre-defined conventions. Examples of these conventions are:

Date or DateTime included in field name, e.g. orderPlacedDateTime;
Dates and DateTimes are in ISO 8601 format;
Country codes is in ISO 3166-1 format;
ENUM values are uppercase;
Primary identifiers follow the logic of <object>Id (e.g. orderId, inboundId, shipmentId, etc.).

Besides the pre-defined 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