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 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
- 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.
- Check report request submission status with the Report Request Status API, which returns all details about the report status.
- Once the report has a status of READY, you can now download the report with the Download Report URL API.
- (Optional): You can also get a list of all report requests with the Get All Report Requests API.
- (Optional): If you set up notifications with 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 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 (e.g. reportType=CANCELLATION).reportVersion– Specify report version (e.g. 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 (e.g. 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. To set up a notification, see Notifications.
Step 2: Get report availability status
To find out if the report is ready for download, call 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 (e.g. 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, See 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 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 examplereportType=CANCELLATIONfor 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 examplerequestStatus=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 5: Download the report URL
To download a report you requested, call 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
requestIdis 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.
| Error Code | Description |
|---|---|
| SYSTEM_ERROR | There is an error in the system. Please wait and try again later. |
| INVALID_REQUEST_PARAM | Missing a required query parameter. Make sure you specified all required parameters. (e.g. reportType, requestId) |
| INVALID_REQUEST_PARAM | If the submission start date is beyond 30 days of the report expiration time, you will get an error. |
| INVALID_REQUEST_PARAM | Possibly missing start and end dates for Get All Reports API request. Try again with both dates provided. |
| INVALID_REQUEST_PARAM | Date specified might not be in correct date format. |
| MISSING_REQUEST_HEADER | The header is missing content. Make sure all required header parameters (e.g. channelType) are specified in the API call. |
| MISSING_REQUEST_PARAM | Make sure to specify the required request parameter (e.g reportType). |
| CONTENT_NOT_FOUND | The requestId could not be found. Try again with correct request ID. |
