Retailer API migration guide from v4 to v6

Versions 5 and 6 of the Retailer API introduced some significant improvements to’s partner developer tools. We recommend upgrading from v4 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 v4 before it is removed on 04 April 2021.

New features in v5 and v6

New features in v5 are not documented in the migration guide. For details regarding the implementation of these features, refer to the v5 release notes, v6 release notes, and related documentation.

v5 features

  • Search terms: see the items that customers are searching for.

  • Get orders with all statuses: track all orders from the last 48 hours, even if they have been shipped or cancelled.

  • Replenishments API: the Inbounds API is now the Replenishments API, and includes the ability to use’s first mile replenishments.

v6 features and improvements

  • Promotions API (Beta): follow promotions of campaigns that apply to your offers. This gives you the opportunity to review and adjust your prices so that you can participate in a promotion.

  • The Subscriptions API has been moved out of Beta.

  • Subscribe to shipping information: via the Subscription API it is now possible to subscribe to shipping information. As a result, you do not always have to retrieve shipping information from the link, but only if you receive a notification that something has changed in the shipment.

  • Shipping labels: There are 2 improvements to shipping labels:

    • When fetching delivery options, makes a recommendation (recommended) for the best shipping option.

    • When fetching delivery options, the name of the shipping label is sent back so that the type of label is more transparent.

  • Tracking shipments: Transport events are now included in GET single shipments, which allow you to track shipment events when they are updated in the system. This gives you more insight into the shipments.

Changed resources from v4

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

  • We changed IDs from integers to strings throughout v5 of the Retailer API. In the case of the Process status, the process-status-id is now a string. This will affect every endpoint that uses the processStatusId - often called id - in its response message. See the migration guides for more information. If you have this field stored, you should update it.

  • All Beta features, including Promotions, will be moved to v7 on 1 October, and removed from earlier versions on 1 November. You should migrate your endpoints if you are still using these features.

Table 1. Table of changed resources
Resource Impact


No changes

Replenishments (formerly Inbounds)

Resource has been replaced


Medium (8 changes)


Low (1 change)


Low (2 changes)


Low (7 changes)


Medium (11 changes)

Product content

Low (4 changes)

Process status

High (5 changes)


Medium (21 changes)


Medium (8 changes)

Shipping labels

Low (5 changes)


Low: (2 changes)