Call this endpoint to download a Microsoft Excel (.xlsx) file containing order-level data that contributes to your returns metrics. Use the report to audit changes in returns performance and investigate specific orders, items, and SKUs.

Use the optional reportDuration query parameter to select a trailing reporting window. The default reporting window is 60 days.

Use the optional conditionType query parameter to retrieve a report for new or resold offers. Allowed values are NEW and RESOLD. When conditionType is omitted, the report is generated for both NEW and RESOLD offers.

This page describes an example using the required headers and common query parameters to retrieve a returns performance report. For a full list of customization options and additional capabilities, refer to the Marketplace Insights API Reference.

Endpoint

GET https://marketplace.walmartapis.com/v3/insights/performance/returns/report

Query parameters

Use conditionType=NEW to retrieve orders for new offers.

Use conditionType=RESOLD to retrieve orders for resold offers.

Sample request

Use this sample request to download the seller’s returns performance report for resold offers during the past 60 days.

curl --request GET \ --url 'https://marketplace.walmartapis.com/v3/insights/performance/returns/report?reportDuration=60&conditionType=RESOLD' \ -H "WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6" \ -H "WM_MARKET: US" \ -H "WM_SVC.NAME: Walmart Marketplace" \ -H "WM_SEC.ACCESS_TOKEN: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM....." \ -H "WM_GLOBAL_VERSION: 3.1" \ -H "Authorization: Basic YzcyOTFjNmItNzI5MC00...." \ -H "Accept: application/octet-stream" \ --output returns-performance-report.xlsx

from pathlib import Path import requests url = ( "https://marketplace.walmartapis.com" "/v3/insights/performance/returns/report"
) headers = { "WM_QOS.CORRELATION_ID": "b3261d2d-028a-4ef7-8602-633c23200af6", "WM_MARKET": "US", "WM_SVC.NAME": "Walmart Marketplace", "WM_SEC.ACCESS_TOKEN": "eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....", "WM_GLOBAL_VERSION": "3.1", "Authorization": "Basic YzcyOTFjNmItNzI5MC00....", "Accept": "application/octet-stream",
} params = { "reportDuration": 60, "conditionType": "RESOLD",
} response = requests.get( url, headers=headers, params=params, timeout=60,
) response.raise_for_status() output_file = Path("returns-performance-report.xlsx")
output_file.write_bytes(response.content) print(f"Report saved to {output_file}")

Modify your code

• Use a unique WM_QOS.CORRELATION_ID for each request.
• Replace the example WM_SEC.ACCESS_TOKEN value with a valid access token.
• Replace the example Authorization value with your encoded credentials.
• Set reportDuration to the number of past days to include. When omitted, the API uses 60.
• Set conditionType to NEW or RESOLD.
• Omit conditionType to retrieve orders for both NEW and RESOLD conditions.
• Save the response body as an .xlsx file. Do not parse a successful response as JSON.

To retrieve a report for new offers:

conditionType=NEW

To retrieve a report for resold offers:

conditionType=RESOLD

Sample response

A successful response contains the Microsoft Excel file as binary data.

Content-Type: application/octet-stream <BINARY_XLSX_FILE_CONTENT>

The response is not a JSON object. Save the response body directly to a file with an .xlsx extension.

Result

A successful request returns HTTP 200 OK with the Excel report in the response body.

The report contains order-level data contributing to returns metrics for the requested reporting duration and condition type.

The endpoint can also return:

• HTTP 204 No Content when no report content is available for the seller.
• HTTP 500 Internal Server Error when the service cannot process the request.

Error handling

Rate limits

If you submit too many requests in a short period, you may exceed Walmart’s rate limits and receive HTTP 429 Too Many Requests.

For more details about throttling and retry best practices, refer to the Rate Limiting Guide.