On-request Reports – Marketplace – US – API Doc

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 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

Request an item report (BETA)

The Item report version 1 is a new report that you can request whenever you need it. The on-request item report is restructured, with different column names and locations.

Once the report is available, you can download it to return all the information associated with your items that are set up on Walmart’s platform.

Note: All example API calls shown assume the Walmart API endpoint: https://marketplace.walmartapis.com

Step 1: Request the item report

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

For example, call v3/reports/reportRequests?reportType=ITEM&reportVersion=v1

Specify values for all required parameters:

reportType – Specify which report you want to request (e.g. reportType=ITEM).
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 example reportType=ITEM 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 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 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.

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.

Request an inventory report (BETA)

Sellers can use the on-request Inventory report to view their entire inventory for all items across all fulfillment centers.

Once the report is available, sellers can download it to return all the information associated with the items that are set up on Walmart’s platform.

OPTIONAL: Use an app to parse the CSV file

Instead of downloading the CSV file, you can use an app to parse the CSV file for you, you can use the Java code shown in the Pre-generated Reports guide. See Parse reports CSV file with Java.

What’s in the Report file

The report shows individual rows for each fulfillment center that holds inventory for that item. For example, if you have one item at four fulfillment centers, you will see 4 rows in the report for that item, each row for the corresponding fulfillment center (aka “ship node”).

Here is an example to show the Report CSV file opened in a spreadsheet application.