On-request reports API Overview

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

Report generation time

After you request the report, it takes 15 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 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. 
5. (Optional): If you set up notifications with the Create Subscriptions API, when you receive the notification that the report is ready, you can retrieve it for download with the Download Report URL API.

Diagram: Report Request Workflow

How to request a report

Step 1: Request the cancellation 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=CANCELLATION).
• 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.

You can also set up a notification to trigger once the report status is READY. For information on how to set up a notification, go to Notifications.

Step 2: Get report availability status

To find out if the report is ready for download, call the Report Request Status API to retrieve 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) Subscribe to an event notification

To get a notification when the report you request is ready to download, create a Webhook notification. When the report status changes to READY, this triggers the notification.

For steps to subscribe, go to Notifications. In addition to other required parameters, make sure to set resourceName to REPORTS, eventType to REPORT_STATUS, eventVersion to V1.

For example:

"resourceName": "REPORTS",
"eventType": "REPORT_STATUS",
"eventVersion": "V1",
"description": "Notification for report status"

Step 4: (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=CANCELLATION for cancellation 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 the start date.
• requestSubmissionEndDate – Specify a range of report requests and provide the 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 the 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 5: 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 INVALID_REQUEST_PARAM error, depending on which API you call, and which parameters are required for that API.