Retailer API migration guide from V3 to V5

Version 5 of the Retailer API introduces some significant improvements to’s partner developer tools. We recommend upgrading to V5 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 V3 before it is removed on 1 October 2021.

New features in v4 and v5

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

Changed resources from v3

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

  • 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 the Unpublished Offers Report and the Subscriptions API, will be moved to V6 on 1 April, and removed from earlier versions on 1 May. You should migrate your endpoints if you are still using these features.

Table 1. Table of changed resources
Resource Impact


Low (4 changes)

Replenishments (previously Inbounds)

Resource has been replaced


Medium (10 changes)


Low (8 changes)


Low (4 changes)


High (17 changes)


High (63 changes)


High (61 changes)

Process status

High (5 changes)


Endpoints removed


High (48 changes)


High (48 changes)

Shipping labels

Low (3 changes)


Low (2 changes)