---
updatedAt: 2026-07-09T21:27:40.000Z
---

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

1. **[Item setup](/us-marketplace/docs/item-management-api-overview-1):** Create or register products (SKUs) with Walmart using the Marketplace Item Management API.
2. **[Inventory management](/us-marketplace/docs/inventory-overview):** Keep SKU quantities accurate using the Marketplace Inventory API.
3. **[Order management](us-marketplace/docs/order-management-api-overview):** Retrieve and confirm orders, shipments, and cancellations through the Orders API.
4. **[Reporting and insights](/us-marketplace/docs/integrate-with-marketplace-apis):** Analyze catalog, inventory, and performance data using On Request Reports and related Analytics and Insights APIs.
5. <Anchor target="_blank" href="/us-marketplace/update/docs/walmart-fulfillment-services-wfs-reports">**Walmart Fulfillment Services (WFS)**</Anchor>: Provide detailed visibility into sales, growth, inventory, payments and fees.

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

<Table>
  <thead>
    <tr>
      <th>
        Scenario
      </th>

      <th>
        Create or manage
      </th>

      <th>
        Retrieve or download
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Single report job
      </td>

      <td>
        <code>POST /v3/reports/reportRequests?reportType={TYPE}&amp;reportVersion={VERSION}</code><br />Creates a report request and returns a <code>requestId</code>.
      </td>

      <td>
        <code>GET /v3/reports/reportRequests/{requestId}</code><br />Checks status (<code>RECEIVED</code> → <code>INPROGRESS</code> → <code>READY</code> or <code>ERROR</code>).
      </td>
    </tr>

    <tr>
      <td>
        Recent requests (last 30 days)
      </td>

      <td>
        N/A
      </td>

      <td>
        GET /v3/reports/reportRequestsLists recent requests with optional query filters.
      </td>
    </tr>

    <tr>
      <td>
        Download a ready report
      </td>

      <td>
        N/A
      </td>

      <td>
        <code>GET /v3/reports/downloadReport?requestId={requestId}</code><br />Returns a pre‑signed <code>downloadURL</code>.
      </td>
    </tr>

    <tr>
      <td>
        Scheduled recurring reports
      </td>

      <td>
        <ul>
          <li><code>POST /v3/reports/schedules</code> Create a schedule.</li>
          <li><code>PUT /v3/reports/schedules/{scheduleId}</code> Update a schedule.</li>
          <li><code>DELETE /v3/reports/schedules/{scheduleId}</code> Delete a schedule.</li>
        </ul>
      </td>

      <td>
        <ul>
          <li><code>GET /v3/reports/schedules</code> List schedules.</li>
          <li><code>GET /v3/reports/schedules/{scheduleId}</code> Get a single schedule.</li>
        </ul>
      </td>
    </tr>
  </tbody>
</Table>

### 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, refer to the On Request Reports API reference:

* [Create Report Request](/us-marketplace/reference/generatereport)
* [Get All Report Requests](/us-marketplace/reference/getrequestsstatus)
* [Report Request Status](/us-marketplace/reference/getsinglerequeststatus)
* [Download Report URL](/us-marketplace/reference/downloadreport)
* [Report Scheduler endpoints](/us-marketplace/reference/post_v3-reports-schedules)

## Prerequisites

Complete the following before integrating the On Request Reports API:

* Complete the steps in the Getting started guide:

  * If you are a seller, refer to the [Marketplace getting started guide for sellers](/us-marketplace/docs/direct-sellers).
  * If you are an approved Solution Provider, refer to the [Marketplace getting started guide for solution providers](/us-marketplace/docs/marketplace-solution-providers).
* OAuth 2.0 authentication is required. Ensure you have obtained the credentials and tokens before making API requests. For more information, refer to [OAuth 2.0 authorization](/us-marketplace/docs/oauth-20-authorization).
* (Recommended) Set up **REPORT\_STATUS** webhooks so you do not need to poll. Refer to [Notifications overview](/us-marketplace/docs/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](/us-marketplace/docs/request-an-item-report)** and **[Request an inventory report](/us-marketplace/docs/request-an-inventory-report)**.
* Set up the **[Reports Scheduler](/us-marketplace/docs/reports-scheduler)** for recurring generation.

## Related

* **Event notifications:** [Create event notifications](/us-marketplace/docs/add-event-notifications) and subscribe to the <code>REPORT\_STATUS</code> event.
* **Postman collection:** Try the On Request Report Management requests in the Walmart US public collection.
* **Analytics and insights:** Explore reporting and performance APIs under [Integrate with Marketplace APIs](/us-marketplace/docs/integrate-with-marketplace-apis).

<br />