---
updatedAt: 2026-08-20T00:09:48.000Z
---

# Request a customer returns report

Use this report to request Walmart Fulfillment Services (WFS) customer return information for a selected time period. The report helps you retrieve customer return data on demand, track report generation status, and download the report when it is ready.

> **Data freshness:** On-request reports are generated after you submit a request. Use the report request status endpoint to confirm when the report is ready to download.

## Endpoint

```http
POST https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=WFS_CUSTOMER_RETURNS&reportVersion=v1
```

The request body is optional. When the request is accepted, the API returns a `requestId` you can use to track status and download the report.

## Sample request

```http
POST https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=WFS_CUSTOMER_RETURNS&reportVersion=v1
Accept: application/json
Content-Type: application/json
WM_QOS.CORRELATION_ID: <guid>
WM_SEC.ACCESS_TOKEN: <access-token>
WM_SVC.NAME: Walmart Service Name

{}
```

## Sample request with date filters

```http
POST https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=WFS_CUSTOMER_RETURNS&reportVersion=v1
Accept: application/json
Content-Type: application/json
WM_QOS.CORRELATION_ID: <guid>
WM_SEC.ACCESS_TOKEN: <access-token>
WM_SVC.NAME: Walmart Service Name

{
  "dataStartTime": "2025-10-01T00:00:00Z",
  "dataEndTime": "2025-10-31T23:59:59Z"
}
```

> Use `dataStartTime` and `dataEndTime` to filter the report data range. Use ISO 8601 format: `YYYY-MM-DDTHH:mm:ssZ`.

## cURL

```curl
curl --request POST \
  --url 'https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=WFS_CUSTOMER_RETURNS&reportVersion=v1' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'WM_QOS.CORRELATION_ID: <guid>' \
  --header 'WM_SEC.ACCESS_TOKEN: <access-token>' \
  --header 'WM_SVC.NAME: Walmart Service Name' \
  --data '
{
  "dataStartTime": "2024-08-01T00:00:00Z",
  "dataEndTime": "2024-08-31T23:59:59Z"
}
'
```

> Use a new GUID for each call. Keep the `requestId` to track status and download the report.

## Track and download

1. **Check status**

   ```http
   GET https://marketplace.walmartapis.com/v3/reports/reportRequests/{requestId}
   ```

   Status values: `RECEIVED`, `INPROGRESS`, `READY`, `ERROR`.

2. **Download**

   ```http
   GET https://marketplace.walmartapis.com/v3/reports/downloadReport?requestId={requestId}
   ```

You can also retrieve all report requests created within the last 30 days.

## When to use this report

Use this report to:

* Request WFS customer return information on demand
* Retrieve customer return data for a selected date range
* Track report generation status before downloading
* Download the generated report when the request status is `READY`
* Review report requests submitted within the last 30 days

## Report contents

The report output depends on the `WFS_CUSTOMER_RETURNS` report schema and report version. The on-request report workflow returns request-level information such as:

* `requestId`
* `requestStatus`
* `requestSubmissionDate`
* `reportType`
* `reportVersion`
* `reportGenerationDate`, when the report is generated

## Next steps

* Save the `requestId` from the create report response
* Use the status endpoint to check when the report is ready
* Download the report when `requestStatus` is `READY`
* Use date filters to narrow the report data range

<br />