On-request Reports API Overview

The On-request Reports API enables you to request item related reports immediately about your items for faster retrieval. Now you can request a report at any time, and then you can download it.

Report generation time

After you request the report, it takes up to 45 minutes to generate. Then, it is available for download.

Report retention period

Reports that you request are retained for 30 days. You can request the report for 30 days with the request ID for the report, you don’t need to request a new one.

Request limit

You can request one report, for each report type, per hour. Although you can request multiple report types at the same time, you can make a request for each report type only once per hour.

Report request workflow

1. Create a report request with the Create Report Request API. For each request, the system creates a Request ID that the seller uses to track the status of the requested report.

2. Check report request submission status with the Report Request Status API, which returns all details about the report status.

3. Once the report has a status of READY, you can now download the report with the Download Report URL API.

4. (Optional): You can also get a list of all report requests with the Get All Report Requests API.

Diagram: Report Request Workflow

How to request a report

Step 1: Request the report

To request an item report, call the Create Report Request API.

For example, call v3/reports/reportRequests?reportType=REPORT-TYPE&reportVersion=v1

Replace “REPORT-TYPE” with the report type you need to request.

Specify values for all required parameters:

• reportType – Specify which report you want to request (for example: reportType=ITEM_MX).
• reportVersion – Specify report version (for example: reportVersion=v1).

Upon success, the API call returns a requestID that you can use to find out if the report is ready for download and status of the request (for example, RECEIVED or INPROGRESS). It also returns values for requestSubmissionDate in UTC format: YYYY-MM-DDTHH:mm:ssZ.

Step 2: Get report availability status

To find out if the report is ready for download, call the Report Request Status API to retrieve the report request status. When status is READY, you can download the report. The API can only retrieve details of requests created in the past 30 days.

For example, call v3/reports/reportRequests?{requestId} with the request ID.

Upon success, this call retrieves the status of the specified request ID (for example: SUBMITTED, INPROGRESS, READY, or ERROR).

Step 3: (Optional) Get a list of all requests

To get a list of all report requests in the last 30 days, call the Get All Report Requests API. Request log does not continue to store requests past 30 days.

For example, call /v3/reports/reportRequests directly to retrieve a list of all requests.

(Optional): You can also filter the list with these query parameters:

• reportType – Specify a specific type of report only, for example reportType=ITEM_MX for item Report.
• requestId – Specify a single request ID to return.
• requestStatus – Request only report requests with one status to be returned: RECEIVED, INPROGRESS, READY, ERROR. For example, requestStatus=READY.
• requestSubmissionStartDate – Specify a range of report requests and provide start date.
• requestSubmissionEndDate – Specify a range of report requests and provide end date.

Upon success, it retrieves a list of all reports that were requested with the Create Report Request API. It provides a list of request IDs by request submission date.

Example: Request all Reports that are Ready

If you want to return all current report requests that are currently ready, you can call:

/v3/reports/reportRequests?requestStatus=READY

Step 4: Download the report URL

To download a report you requested, call the Download Report URL API and specify the requestID sent by the report status notification, or from a status API call.

For example, call /v3/reports/downloadReport?requestId={requestId}

Upon success, you receive the URL to download the report along with the URL expiration time:

• downloadURL – the URL to download the report.
• downloadURLExpirationTime – the download URL expiration time.

To avoid errors, make sure to check that these situations don’t apply to your request:

• The request has expired. In this case, the report is no longer available.
• If the report is not available yet, check to see that status is not INPROGRESS.
• Could be either system error, or data errors.
• If the requestId is invalid. Make sure you have the correct ID, or that it hasn’t expired after 30 days.

Troubleshooting and Error Codes

If you get failures, here are some hints for how to solve these possible errors. Notice there are several reasons why you might get an INVALID_REQUEST_PARAM error, depending on which API you call and which parameters are required for that API.