Release notes retailer API version 3

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

JSON payload validation covered several specific validations:

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

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.

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

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

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.

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.

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

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

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.

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

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

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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: