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, and create a shipping label. AshippingLabelId
is given back in the response. -
Get shipping label: based on the
shippingLabelId
retrieve the shipping label in PDF format.
In addition the following changes were made:
-
The V4 ship order item endpoint was created to use the new shipping label on the shipment of an order item.
-
Use
shippingLabelId
to confirm the shipment with the shipping label requested through the request shipping label endpoint. -
A new order item cancellation endpoint was introduced.
-
For a complete shipping label flow the change transport endpoint was migrated to API v4.
Demo documentation for the shipping label flow is available here: |
Version 3.25
Version | Release Date | Release Type | Breaking Changes |
---|---|---|---|
3.25 |
14-07-2020 |
Minor |
No |
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 loads 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.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 scenarios 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 a SUCCESS status, and the id was used to retrieve the offer export file before it was ready.
The offer export id is now exposed 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. |
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 reenabled 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 reenabled 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 |
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 can be found 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 occasionally provide millisecond precision. 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 forecasts of a given offer.
Demo environment information for insights can be found here. |
Version 3.12
Version | Release Date | Release Type | Breaking Changes |
---|---|---|---|
3.12 |
28-10-2019 |
Minor |
No |
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.
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.
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, and offer creation requests containing this value will fail.
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; bug fixes 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.
Header Name | Value |
---|---|
|
|
|
|
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 and linked below.
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
Previously the deliveryCode
field value 3-4d was included in the create offer documentation. This deliveryCode
is no longer supported, and using it will 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 the 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, and 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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 backend 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. |