The On Request Reports API lets users request item reports.

Request a report at any time, subscribe to notifications when the report is ready, and download the requested report.

Report generation time

Reports take 15 to 45 minutes to generate and are available for download after they are generated.

Report retention period

Requested reports are retained for 30 days. Request a report for up to 30 days with the requestId for the report. There is no need to request a new one each time.

Request limit

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

Report request workflow

The following is the report request workflow:

1. Create a report request with the Create report request (POST /v3/reports/reportRequests). For each request, the system creates a requestId that the supplier uses to track the status of the requested report.
2. Check the report request submission status with the Retrieve details on single report request (GET /v3/reports/reportRequests/{requestId}), which returns all details about the report status.
3. (Optional): Users can retrieve a list of all report requests with the Retrieve all report request (GET /v3/reports/reportRequests).
4. Once the report has a READY status, users can download the report with the Download report URL request (GET /v3/reports/downloadReport).

The following diagram details the report request workflow.

How to request a report

Step 1: Request an item report

To request an item report, call the Create report request (POST /v3/reports/reportRequests).

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

Replace REPORT-TYPE with the report type to request; for example, INVENTORY_DSV or ITEM_CONFIGURATION_DATA.

Specify values for all required parameters, as detailed in the following list:

• reportType: Specifies which report to request; for example, reportType=INVENTORY_DSV.
• reportVersion: Specifies the report version; for example, reportVersion=v1.

Upon success, the API call returns a requestId. Use that value to find out if the report is ready for download and the status of the request. Statuses include: RECEIVED, INPROGRESS, READY, and ERROR.

The API call also returns values for requestSubmissionDate in ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ.

Step 2: Get report availability status

To find out if the report is ready for download, call the Retrieve details on single report request (GET /v3/reports/reportRequests/{requestId}) to retrieve report request status. Users can download the report when the status is READY.

Note: This API call can only retrieve details of requests created in the past 30 days.

The following is an example API call:

1. Call v3/reports/reportRequests?{requestId} with the needed requestId.
2. Upon success, this API call retrieves the status of the specified requestId. Statuses include: RECEIVED, INPROGRESS, READY, and 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 Retrieve all report requests request (GET /v3/reports/reportRequests).

Note: The request log does not continue to store requests past 30 days.

The following is an example API call:

1. Call /v3/reports/reportRequests directly to retrieve a list of all requests.
2. Filter the list with these query parameters:
   • reportType: Specifies the type of report; for example, reportType=DSV_INVENTORY for DSV inventory report.
   • requestId: Specifies a single request ID to return.
   • requestStatus: Specifies report requests with one status to be returned, such as RECEIVED, INPROGRESS, READY, or ERROR for example, requestStatus=READY.
   • requestSubmissionStartDate: Specifies a range of report requests by providing a start date.
   • requestSubmissionEndDate: Specifies a range of report requests by providing an end date.
     
     

Upon success, the API call retrieves a list of all reports that were requested with the Retrieve all report requests request (GET /v3/reports/reportRequests). The response provides a list of request IDs sorted by request submission date.

Here is an example of a request for all reports in READY status:

1. Call /v3/reports/reportRequests?requestStatus=READY.
2. Upon success, the response provides a list of request IDs sorted by request submission date.

Step 4: Download the report URL

To download a requested report, call the Download report URL request (GET /v3/reports/downloadReport). Specify the requestId sent by the report status notification or from the Retrieve details on single report request (GET /v3/reports/reportRequests/{requestId}).

Here is an example call:

1. Call /v3/reports/downloadReport?requestId={requestId}
2. Upon success, the user receives the URL to download the report along with the URL expiration time:
   • downloadURL: Specify the URL to download the report.
   • downloadURLExpirationTime: Specify the download URL expiration time.
     
     

To avoid errors, make sure to check that these situations do not apply to the request:

• The request has expired. Expiration occurs after 30 days. If expired, the report is no longer available.
• The report is in INPROGRESS status. If the report is not available yet, check to see that status is not in the INPROGRESS status.
• The report is in an error state. Ensure system errors or data errors are not present.
• The requestId is invalid. The user must ensure they have the correct request ID, or that it has not expired after 30 days.

Troubleshooting and Error Codes

Here are some hints for how to solve these possible errors in the event of failures.

Notice there are several reasons why users might get an INVALID_REQUEST_PARAM error. These reasons depend on which API the users call and which parameters are required for that API.