Amazon Services
Amazon Marketplace Web Service (Amazon MWS) Documentation

Deprecation Notice:

Amazon Marketplace Web Service (MWS) will no longer be available after March 31, 2024. All MWS developers must migrate to Selling Partner API (SP-API) to avoid service disruptions. Refer to the Migration Hub for more information.

Amazon MWS Documentation

Building robust Amazon MWS applications

Your Amazon Marketplace Web Service (Amazon MWS) client applications should gracefully handle changes to the reports and response elements that Amazon MWS returns, even without prior change notification from Amazon.

Changes to reports returned by Amazon MWS

Build report parsers into your client applications that can gracefully handle the following types of changes to the reports that Amazon MWS returns:

  • New fields in reports. Your client applications should handle new fields in reports as they become available. These include new columns in flat file reports and new elements in XML reports.
  • New field values in reports. Your client applications should handle new field values in reports as they become available. These include new column values in flat file reports and new element values in XML reports.

Important: If you choose to use report XSDs published by Amazon to validate reports returned by Amazon MWS, be sure to build error handling into your validation logic. Any report validation included in your client application should be able to gracefully handle new, unrecognized response elements or response element values.

Changes to Amazon MWS response elements

Build your client applications to gracefully handle the following types of changes to Amazon MWS responses:

  • New response elements. Your client applications should handle new, unrecognized response elements.
  • New response element values. Your client applications should handle new, unrecognized response element values.

Best practices

What does it mean to "gracefully handle" changes? Here are some examples:

  • Expect changes. At a minimum, ensure that your client applications do not break when new response elements, response element values, report fields or report field values are introduced by Amazon. Don’t code your client applications to expect only certain elements, fields, and values.
  • Log unrecognized elements, fields, or values. Keep a log of all unrecognized elements, fields, or values returned by Amazon MWS. You can use this log to flag new functionality that has been introduced by Amazon, and then update your client application to take advantage of this functionality.
  • Surface unrecognized elements, fields, or values. If Amazon MWS begins returning a report with a new field, for example, you might devise a way to automatically surface the new field values in your client application in a way that is useful to your users.
  • Expect response elements in any order. Response elements can be returned in any order within a structure. Ensure that your client applications do not depend on the order in which response elements are returned by Amazon MWS.