Guides
My Account

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

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

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

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

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

    Status values: RECEIVED, INPROGRESS, READY, ERROR.

  2. Download

    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

Updated about 19 hours ago