Building Robust Amazon SP-API Applications

Your SP-API client applications should handle changes to reports and response elements that SP-API returns, even without prior notification from Amazon.

Changes to reports returned by SP-API

Build report parsers into your client applications that can handle the following types of changes to the reports that SP-API 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.

📘

Build in error handling if you use report XSDs

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

Changes to SP-API response elements

Build your client applications to gracefully handle the following types of changes to SP-API 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

• Expect changes. 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, or values.
• Log unrecognized elements, fields, or values. Keep a log of all unrecognized elements, fields, or values returned by SP-API. 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 SP-API 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 SP-API.
• Use the latest model version. To prevent null enum values, use the most recent version of the API model.