On-request reports API overview

Use the Walmart Marketplace On Request Reports API to generate and download operational reports on demand. Walmart sellers and approved Solution Providers can:

Request a report by type and version whenever you need it.
Add filters (row filters, date range, exclude columns) to reduce file size and noise.
Track status for each request and receive a REPORT_STATUS webhook when it is ready.
Download the file using a time limited URL.
(Optional) Schedule recurring reports with the Reports Scheduler.

How it works

Overall seller journey

In a common user journey, a seller or approved Solution Provider might complete this Marketplace flow:

Item setup: Create or register products (SKUs) with Walmart using the Marketplace Item Management API.
Inventory management: Keep SKU quantities accurate using the Marketplace Inventory API.
Order management: Retrieve and confirm orders, shipments, and cancellations through the Orders API.
Reporting and insights: Analyze catalog, inventory, and performance data using On Request Reports and related Analytics and Insights APIs.

After you submit a report request, generation typically completes in 15–45 minutes. Requested reports are retained for 30 days. You can view request history for the last 30 days.

On request reports flow

Within reporting, a typical flow is to create a report job, monitor status, and then download the file. The core endpoints pair request creation with retrieval:

Scenario	Create or manage	Retrieve or download
Single report job	`POST /v3/reports/reportRequests?reportType={TYPE}&reportVersion={VERSION}` Creates a report request and returns a `requestId`.	`GET /v3/reports/reportRequests/{requestId}` Checks status (`RECEIVED` → `INPROGRESS` → `READY` or `ERROR`).
Recent requests (last 30 days)	N/A	`GET /v3/reports/reportRequests` Lists recent requests with optional query filters.
Download a ready report	N/A	`GET /v3/reports/downloadReport?requestId={requestId}` Returns a pre‑signed `downloadURL`.
Scheduled recurring reports	`POST /v3/reports/schedules` Create a schedule. `PUT /v3/reports/schedules/{scheduleId}` Update a schedule. `DELETE /v3/reports/schedules/{scheduleId}` Delete a schedule.	`GET /v3/reports/schedules` List schedules. `GET /v3/reports/schedules/{scheduleId}` Get a single schedule.

Flow diagram

This diagram shows the standard on request flow with optional webhooks and scheduling.

Reference guide

This guide explains how to use the On Request Reports API, providing practical examples and step‑by‑step instructions for integrating report generation into your solution.

For full technical details, including endpoints, parameters, and brief descriptions, see the On Request Reports API reference:

Prerequisites

Complete the following before integrating the On Request Reports API:

Complete the steps in the Getting started guide:
- If you are a seller, see the Marketplace getting started guide for sellers.
- If you are an approved Solution Provider, see the Marketplace getting started guide for solution providers.
OAuth 2.0 authentication is required. Ensure you have obtained the credentials and tokens before making API requests. For more information, see OAuth 2.0 authorization.
(Recommended) Set up REPORT_STATUS webhooks so you do not need to poll. See Notifications overview.

Commonly used terms

Term	Description
reportType	The report family you are requesting (for example, `ITEM`, `INVENTORY`, `PROMO`).
reportVersion	Version of the report schema (for example, `v1`, `v4`, `v6` for Item).
requestId	The unique ID returned when you create a report request. Use it to check status and download the file.
Status	Report job lifecycle: `RECEIVED` → `INPROGRESS` → `READY` or `ERROR`.
Retention window	Reports and request history are available for 30 days.
Default lookback	If you do not pass filters for certain historical reports, the default lookback is the past 30 days.

Market availability

The On Request Reports API is available for sellers listing on Walmart marketplaces in the United States, Canada, and Mexico. Availability can vary by report type. Check each report guide for market coverage.

Next steps

Learn how to use filters when requesting reports to shape output and reduce file size.
Try a report: Request an item report and Request an inventory report.
Set up the Reports Scheduler for recurring generation.