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

What you should know about the Amazon MWS Reports API section

The Reports API section of the Amazon Marketplace Web Service (Amazon MWS) API lets you request various reports that help you manage your Sell on Amazon business. Report types are specified using the ReportTypes enumeration.

Amazon periodically adds new fields and field values to reports. Be sure to build report parsers into your Amazon MWS applications that can gracefully handle these types of report updates. For more information, see Building robust Amazon MWS applications.

Important: Your access to Amazon MWS data depends on the role Amazon assigns you after you submit the Developer Registration and Assessment form. For more information see Registering to use Amazon MWS.

The report process begins by creating a report request. Next, you obtain a list of report requests which shows the report request identifier and status of each requested report. Finally, you use the report request identifier from this listing to get the actual report. The process steps are as follows:

  1. Submit a report request using the RequestReport operation. This is a request to Amazon MWS to generate a specific report. Note that you can also schedule order report requests to be submitted periodically using the ManageReportSchedule operation.
  2. Submit a request using the GetReportRequestList operation to get a list that shows the report requests and the status and ID of each report request. Amazon MWS returns a ReportRequestId for every report requested. When Amazon MWS sets the status of a report request to _DONE_, the report is ready to be retrieved. Some reports create a GeneratedReportId that you can pass to the GetReport operation (see step 4). If you need to cancel a report request, use the CancelReportRequests operation.
    Note: Rather than repeatedly polling the GetReportRequestList operation to find out when report processing is complete, Amazon recommends subscribing to the ReportProcessingFinishedNotification notification. After you subscribe, for each report you request Amazon will send you a push notification when report processing is complete. This makes your workflow more efficient and helps you avoid exceeding the throttling limits of the GetReportRequestList operation. For more information, see Use the ReportProcessingFinished notification when requesting a report.
  3. If no GeneratedReportId was created, submit a request using the GetReportList operation and include the ReportRequestId for the report requested. The operation returns a ReportId that you can then pass to the GetReport operation (see step 4).
  4. Submit a request using the GetReport operation to receive a specific report. You include in the request the GeneratedReportId or the ReportId for the report you want to receive. You then process the Content-MD5 header to confirm that the report was not corrupted during transmission. For more information on working with the Content-MD5 header, see the Amazon MWS Developer Guide.

The following flowchart shows the process for submitting and receiving an on-request report:

You can also schedule order report requests so that they are submitted periodically by using the ManageReportSchedule operation. The Schedule enumeration is used to specify the time period for submitting report requests. You can also get a list of scheduled order report requests using the GetReportScheduleList operation.

The following flowchart shows the process for submitting and receiving a scheduled report:

The Reports API section operations

The Reports API section contains the following operations:

Operation Description Availability
RequestReport Creates a report request and submits the request to Amazon MWS. All marketplaces.
GetReportRequestList Returns a list of report requests that you can use to get the ReportRequestId for a report. All marketplaces.
GetReportRequestListByNextToken Returns a list of report requests using the NextToken, which was supplied by a previous request to either GetReportRequestListByNextToken or GetReportRequestList, where the value of HasNext was true in that previous request. All marketplaces.
GetReportRequestCount Returns a count of report requests that have been submitted to Amazon MWS for processing. All marketplaces.
CancelReportRequests Cancels one or more report requests. All marketplaces.
GetReportList Returns a list of reports that were created in the previous 90 days. All marketplaces.
GetReportListByNextToken Returns a list of reports using the NextToken, which was supplied by a previous request to either GetReportListByNextToken or GetReportList, where the value of HasNext was true in the previous call. All marketplaces.
GetReportCount Returns a count of the reports, created in the previous 90 days, with a status of _DONE_ and that are available for download. All marketplaces.
GetReport Returns the contents of a report and the Content-MD5 header for the returned report body. All marketplaces.
ManageReportSchedule Creates, updates, or deletes a report request schedule for a specified report type. All marketplaces.
GetReportScheduleList Returns a list of order report requests that are scheduled to be submitted to Amazon MWS for processing. All marketplaces.
GetReportScheduleListByNextToken Currently this operation can never be called because the GetReportScheduleList operation cannot return more than 100 results. It is included for future compatibility. All marketplaces.
GetReportScheduleCount Returns a count of order report requests that are scheduled to be submitted to Amazon MWS. All marketplaces.
UpdateReportAcknowledgements Updates the acknowledged status of one or more reports. All marketplaces.