Release notes retailer API version 3

Version 3 of the Retailer API has been deprecated. Please migrate to the v4 API as soon as possible.

Version 3.26

Version Release Date Release Type Breaking Changes

3.26

14-07-2020

Minor

No

Added endpoints for new shipping label flow (V4 - Closed beta)

To accommodate the new shipping label flow new endpoints have been added to V4 of the API:

  • Get delivery options; based on a shipment configuration get the possible shipping labels and their prices for shipping the order item.

  • Request shipping label; based on the the shipment configuration and a shippingLabelOfferId (retrieved from get-delivery-options) create a shipping label. A shippingLabelId is given back in the response.

  • Get shipping label; based on the shippingLabelId retrieve the shipping label in PDF format.

To use the new shipping label on the shipment of an order item the V4 ship order item endpoint is created. Use "shippingLabelId" to confirm the shipment with the shipping label requested through request-shipping-label endpoint. A new order item cancellation endpoint is introduced.

For a complete shipping label flow also the change transport endpoint is migrated to V4 of the API.

Demo documentation available:

Version 3.25

Version Release Date Release Type Breaking Changes

3.25

14-07-2020

Minor

No

Retail price endpoint added (V4 - Closed beta)

This endpoint enables API users to retrieve the retail prices for an EAN. Currently this endpoint only supports the allowable retail price. Check the documentation for more information.

Version 3.24

Version Release Date Release Type Breaking Changes

3.24

23-06-2020

Minor

No

Process status retention limited to 48 hours

After creating a process status, we currently keep it available for a period of 30 days. We have decided to shorten this period to 48 hours for optimization purposes. API Users should only poll the process status until it has reached an end state, and should locally store the entity and its state if it needs to be available beyond the API retention time.

Currently, process statuses can take up to 3 hours to reach an end state, and will remain unchanged after that. Under normal circumstances process statuses should either reach SUCCESS, FAILURE or TIMEOUT state well before the 48 hours have passed, allowing enough time for API users to retrieve the information.

Upon deletion, the retailer API will return a 404 (or no response in the bulk call). Please make sure these are handled properly to prevent unnecessary load on the API.

Version 3.23

Version Release Date Release Type Breaking Changes

3.23

23-04-2020

Minor

No

Offer export and unpublished offers report quicker to complete

We made an improvement in the handling of offer exports and unpublished offer reports to complete faster. An issue with the previous implementation caused file generation to take longer than necessary, especially for a smaller volume of offers.

Requesting an offer export or unpublished offer report caused incorrect error message

Some users experienced issues with repeatedly requesting an offer export, especially in cases where an offer export or unpublished offer report was requested previously. Instead of getting a process status failure describing that a similar process is already active, you now receive a success message linking to the same report that was previously created. This is due to export files and reports being cached for a period of time to reduce load on backend systems in generating these reports.

Version 3.22

Version Release Date Release Type Breaking Changes

3.22

21-04-2020

Minor

No

Create return failed

A bug in our systems caused the return creation call to fail and end in timeout. The bug has since been resolved allowing returns to be created as normal.

Version 3.21

Version Release Date Release Type Breaking Changes

3.21

15-04-2020

Minor

No

Response code for security issues improved

In some cases where users would have a valid token for access but were not allowed in due to the account being disabled or the users being banned from use of the API, the retailer API would return errors with status 401 (unauthorized) while 403 (forbidden) is the correct response. The API has been updated to return the proper status codes in these situations.

In addition, when the account status for a user cannot be determined, the API would also return a 401 error. This has been modified to be an error 500 (internal server error) to allow clients to respond properly by triggering a retry at a later time.

Version 3.20

Version Release Date Release Type Breaking Changes

3.20

14-04-2020

Minor

No

Unpublished offer report endpoints added (V4 - Closed Beta)

These endpoints enable API users to request and retrieve an unpublished offer report including a reason why the creation of offers failed. Check the Redoc documentation and demo scenario’s for more information.

Redoc documentation:

Demo scenarios for the unpublished offer report here.

Exposing offer export id after an export was successful

The get process status endpoint is used to see if an offer export is successful and to retrieve the offer export id. Unfortunately the offer export id was exposed before status was SUCCESS and the id was used to retrieve the offer export file before it was ready.

With this bugfix we expose the offer export id when the offer export file is ready to be retrieved.

Version 3.19

Version Release Date Release Type Breaking Changes

3.19

06-04-2020

Minor

No

Pick Up Points attribute on Offers (V3 - Closed Beta)

A new list attribute pickUpPoints has been added to the Offers Endpoints (POST, PUT and GET).

This indicates if this Offer should be eligible for delivery at a Pick Up Point.

Demo scenario for offers here.

Pick Up Points attribute on get order and get shipment (V3 - Closed Beta)

The single order and single shipment endpoints now return the fields "pickUpPoint and pickUpPointName" for handling orders and shipments where delivery address is a Pick Up Point.

Demo scenario for get single order here.

Demo scenario for get single shipment here.

Version 3.18

Version Release Date Release Type Breaking Changes

3.18

19-03-2020

Minor

Yes

Breaking change!

Updates on product content endpoint and validation report (V4)

The product content post endpoint for updating product content has been updated with changes in the model:

  • The attribute 'locale' has been replaced by attribute 'language' with possible values 'nl' and 'nl-BE'.

The product content get endpoint for validation report has been updated with changes in the model:

  • The attribute 'status' is now a part of the 'rejectedAttribute' object.

  • The attribute 'reason' on the 'rejectionError' object has been removed.

Demo scenario for product content here here.

Version 3.17

Version Release Date Release Type Breaking Changes

3.17

19-03-2020

Minor

No

Stricter JSON validation didn’t work anymore, now re-enabled with this release

JSON payload validation covered several specific validations:

  • Duplicate detection - Whenever a payload contains duplicate fields we will reject the message. This is to prevent situations where requests might contain a price field twice with different values, making it unpredictable which value will be accepted by the API. Supplying duplicates will result in an error 400.

  • Unknown fields - Fields that are sent to the API and are not defined in the API contract will be rejected. This is to alert callers of incorrect API implementations and to prevent fields being ignored while the requestor is under the impression that the information IS being processed. Supplying unmappable fields will result in an error 400.

  • Array serialization - Arrays are defined in JSON with the use of brackets. However, it is a common practice that arrays of size one can be serialized in JSON without specifying the brackets. We allowed this in the API in the past, but due to a software patch this has been inadvertently been reverted. We re-enabled the logic in this release. Supplying a single item array without brackets will no longer result in an error 400.

The regression issue that caused these validations to stop working has been resolved.

Version 3.16

Version Release Date Release Type Breaking Changes

3.16

10-02-2020

Minor

No

Processing statuses can now be retrieved in bulk

Redoc documentation for retrieving process statuses here.

Demo scenario for get process statuses in bulk here.

Exact delivery date

The single order endpoint now returns the field exactDeliveryDate. This field is only filled when the customer chose an exact date for delivery. This field is empty in case the latestDeliveryDate is filled.

Demo scenarios for get single order here.

Version 3.15

Version Release Date Release Type Breaking Changes

3.15

13-01-2020

Minor

Yes

Breaking change!

Dates are now truncating to seconds

Some endpoints did not follow the ISO 8601 standard, where they would sometimes provide millisecond precision and sometimes not. This has been fixed, no date/time fields will return milliseconds anymore. Endpoints and demo scenarios with changes: Returns, ProcessStatus, Inbounds

Version 3.14

Version Release Date Release Type Breaking Changes

3.14

18-12-2019

Minor

No

New offer insights and sales forecast endpoint (V4 - Closed Beta)

New insights endpoints added on V4 providing information about BuyBox, visits and sales forecast of a given offer.

Demo environment information for insights here

Version 3.13

Version Release Date Release Type Breaking Changes

3.13

17-12-2019

Minor

No

Moved process status endpoints to V4

The process status endpoints have been moved to v4 to be in line with the functionality provided in the v4 beta API. v4 beta users can use the v4 process status endpoints to get insights in their running processes.

Version 3.12

Version Release Date Release Type Breaking Changes

3.12

28-10-2019

Minor

No

Added information for VAT invoice creation

The single order endpoint now returns the fields "vatNumber", "chamberOfCommerceNumber" and "orderReference" for the creation of a VAT invoice. The single shipment endpoint is now also returning the billing details containing the same fields.

Demo scenario for get single order here.

Demo scenario for get single shipment here.

Version 3.11

Version Release Date Release Type Breaking Changes

3.11

09-09-2019

Minor

No

Insights Endpoint added

A new endpoint to fetch your performance the measurements and indicators per week.

Endpoint documentation for insights is available in Redoc.

Demo documentation for insights is available in the demo documentation.

offerId and expiryDate added to single order endpoint

The single order endpoint is now returning the new fields offerId and expiryDate, which were previously missing from the model.

Endpoint documentation for orders is available in Redoc.

Demo documentation for orders is available in the demo documentation.

Removed invalid handlingResult from v4 create offer endpoint

The STILL_APPROVED value has been removed from the list of possible values of handlingResult, as this is not an acceptable value. The documentation has been updated to reflect the change, offer creation requests containing this value will fail.

Endpoint documentation for returns is available in Redoc.

Demo documentation for returns is available in the demo documentation.

Version 3.10

Version Release Date Release Type Breaking Changes

3.10

28-05-2019

Minor

No

New return endpoint added in v4 beta

A new return endpoint has been added to the retailer API v4 (currently in beta) that will support multi-item returns.

Endpoint documentation for returns is available in Redoc.

Added offerId and expiryDate fields to single order endpoint

The model for the get single order endpoint has been expanded and is now also returning the fields offerId and expiryDate in the response.

Endpoint documentation for retrieve single order is available in Redoc.

Alpha and Beta indication added to response headers.

New headers to identify endpoints in Alpha or Beta stage. These show that certain endpoint are under development and/or review.

  • Alpha endpoints - Can be removed or modified at any time, contracts can be broken. Under heavy design/development;

  • Beta endpoints - Are frozen in terms of API but are still developed on; bugfixes and optimizations are still being applied. The API contract is only allowed to break if it cannot be avoided.

We expect endpoints to be in Alpha state for a longer period while working together with partners on an optimal solution. Beta endpoints will remain in beta for a period leading up to the final release.

Table 1. Example alpha/beta headers
Header Name Value

Warning

299 - Alpha API - v5 API is currently in alpha testing phase - See https://developers.bol.com for details

Warning

299 - Beta API - v4 API is currently in beta testing phase - See https://developers.bol.com for details

Demo Scenario Updates

Updated demo scenarios for create return, return list and single return.

Demo scenario documentation for v4 returns is available in the demo documentation.

Version 3.9

Version Release Date Release Type Breaking Changes

3.9

22-05-2019

Minor

No

Improved demo documentation for endpoints get single order and get orders

Demo documentation for get single order endpoints have been added for better testing. To make the get orders calls consistent with the new get single order calls these have also been updated.

Detailed information on the available orders v3 demo endpoints can be found in the demo documentation.

Version 3.8

Version Release Date Release Type Breaking Changes

3.8

02-05-2019

Minor

No

Active rate limits exposed through public endpoint

To satisfy popular demand, a new endpoint has been added to provide information on current rate limits. The endpoint is publicly available, link below.

Please note that rate limits are cached for 3 hours, so data might be stale for a short while. No rights can be derived from this list, as rate limits may be adjusted over time. For current, live insights in the rate limits inspect the headers provided in every call.

Actual rate limits can be retrieved from this endpoint (only available in JSON format).

For more information on rate limits, please consult the information in the conventions documentation.

Improved error handling for unavailable resources in the demo environment

We have received several questions about the retailer API returning http status code 500 error responses on the demo environment when a resource is not available. Instead of returning an http status code 500 we now return a problem with http status code 400 to inform you the requested demo resource is not available.

More information is available in the demo environment documentation.

Version 3.7

Version Release Date Release Type Breaking Changes

3.7

29-04-2019

Minor

No

Removed deliveryCode option 3-4d from the documentation for create a new offer

The previously allowed 'deliveryCode' field value '3-4d' was included in the create offer documentation. This deliveryCode is no longer supported, using it would result in an error response with http status code 500.

We have removed the 3-4d delivery code from the documentation. If you still use this deliveryCode value, the retailer API will return an error response with status code 400.

Endpoint documentation for creating a new offer is available on Redoc.

Version 3.6

Version Release Date Release Type Breaking Changes

3.6

25-04-2019

Minor

No

Patch for transactionFee field always containing 0.00 in get single offer endpoint

Due to a mapping issue, the transactionFee property (on orderItem) was never correctly set, causing it to be 0.00 for all orders retrieved in the get single order call. This has been resolved, the transactionFee will now be populated with the correct value.

Endpoint documentation for get single order is available on Redoc.

Version 3.5

Version Release Date Release Type Breaking Changes

3.5

10-04-2019

Minor

Yes

Breaking change!

Added transport id to shipments response

Fetching shipping labels is a process that required calling multiple endpoints. To simplify and speed up the entire process we have added the transportId in get shipments response.

Endpoint documentation for the shipment list endpoints is available in Redoc.

Added filtering on order id to shipments response

The shipments endpoint has been expanded to allow filtering on order id. Pass the order id as a query parameter to the shipments list endpoint to retrieve the associated shipment.

Endpoint documentation for the shipment list endpoints is available in Redoc.

Renamed offer export file headers

Breaking change!

Some field names in the offer export file have been renamed to better match the single offer endpoint field names. Please adjust any implementations that depend on the field names of the offer export.

Old header name New header Name

offerId

offerId

ean

ean

conditionName

conditionName

conditionCategory

conditionCategory

conditionComment

conditionComment

price

bundlePricesPrice

fulfilmentDeliveryCode

fulfilmentDeliveryCode

retailerStock

stockAmount

onHoldByRetailer

onHoldByRetailer

fulfilmentType

fulfilmentType

mutationDateTime

mutationDateTime

Version 3.4

Version Release Date Release Type Breaking Changes

3.4

05-04-2019

Minor

No

Patch for error in order list endpoint

In some cases, retrieving orders from the retailer API would result in an error 500 due to an error in the logic responsible for creating the response. The bug has been identified and fixed.

Version 3.3

Version Release Date Release Type Breaking Changes

3.3

25-03-2019

Minor

Yes

UUID validator for offer endpoints

Breaking change!

Added a validator to check if offer UUIDs are valid to prevent requests with incorrect ids from reaching the back-end services. Invalid UUIDs were also blocked in the past, but using an invalid UUID now results in a bad request response from the retailer API. Please make sure implementations of this endpoint are able to handle the new errors being returned.

Patch for authentication token clock skew errors

Some API users encountered error messages when trying to do requests on the API mentioning clock skew errors. We’ve patched our applications to allow for a (slight) amount of clock skew between server instances. Please let us know if the problems persist.

Inventory endpoint moved to its own group

The inventory endpoint has been moved to its own group in the Redoc documentation. It has been reported that the endpoint was hard to locate, so we’ve addressed this.

Endpoint documentation for inventory is available in Redoc.

Offer export endpoints added

The endpoints that enable API users to request and retrieve a full export of their offer catalog has been added to the API. Check the Redoc documentation for more information.

Endpoint documentation for requesting an offer export and retrieving the generated offer export is available in Redoc.

Version 3.2

Version Release Date Release Type Breaking Changes

3.2

11-03-2019

Minor

No

Improved accept header validation

Improved validation for accept headers to give better feedback when invalid accept headers are used, so users get more insight into why the request was denied. Using the correct accept headers is vital for the API as the retailer API uses accept header versioning.

For more information, please review the conventions documentation on versioning.

Version 3.1

Version Release Date Release Type Breaking Changes

3.1

07-03-2019

Minor

Yes

Removed unnecessary dateTime field from cancel order request body

Breaking change!

The cancel order request used to contain the dateTime field to specify the cancellation moment. This field is no longer used and has been removed from the request model. Please update your implementation to make sure order cancellations keep functioning.

New request body:

{
    "reasonCode": "BAD_CONDITION"
}

Endpoint documentation for the cancel order endpoint is available in Redoc.

Version 3.0

Version Release Date Release Type Breaking Changes

3.0

04-03-2019

Major

Yes

Initial release of the retailer API for beta testing. Please consult the documentation for more detailed information.