Call this endpoint to get a consolidated snapshot of your returns performance for the last N days (default 60). The API aggregates return rate, GMV loss, impacted orders, risk level, primary drivers, and actionable recommendations, including trend signals. Use this API to monitor performance, prioritize fixes, and track progress over time.

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

The cumulativeRateTrend response parameter uses the statuses in the table below to explain if a trend is a positive or negative change. Trend indicates how this metric has changed compared to the previous report duration ending the day before.

Endpoint

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

Sample request

Use this sample request to retrieve the returns performance summary for the past 60 days

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

import requests url = "https://marketplace.walmartapis.com/v3/insights/performance/returns/summary" headers = { "WM_SEC.ACCESS_TOKEN": "eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....", "Authorization": "Basic YzcyOTFjNmItNzI5MC00....", "WM_QOS.CORRELATION_ID": "b3261d2d-028a-4ef7-8602-633c23200af6", "WM_SVC.NAME": "Walmart Marketplace", "WM_GLOBAL_VERSION": "3.1", "WM_MARKET": "US", "Accept": "application/json"
} params = { "reportDuration": 60
} response = requests.get(url, headers=headers, params=params) print(response.status_code)
print(response.json())

Modify your code

• Use a unique WM_QOS.CORRELATION_ID for each request.
• Replace WM_SEC.ACCESS_TOKEN with your valid access token obtained through authentication.

Sample response

This sample response summarizes your returns performance for the last 60 days, including overall return rate, GMV loss, impacted orders, and trend indicators. It also shows your risk level, the top drivers, and recommendations to reduce returns.

• nonAccountableDrivers are metrics that do not affect the Seller Performance Standards.
• sellerAccountableDrivers are metrics that affect the Seller Performance Standards.
• If an API response includes a single Cumulative rate, it should be interpreted as the seller-accountable rate.
• When a metrics API includes both a Seller Accountable and an Overall or Cumulative rate, the second value represents the total rate, calculated as the sum of seller-accountable and non-accountable drivers.
• In this context, Overall and Cumulative are equivalent and may be used interchangeably.

{ "payload": { "reportDuration": 0, "updatedTimestamp": "2025-12-01T06:30:45Z", "cumulativeRate": 0, "cumulativeRateTrend": "GREEN_UP", "gmvLoss": 0, "gmvLossTrend": "GREEN_UP", "ordersImpacted": 0, "ordersImpactedTrend": "GREEN_UP", "performanceStandard": "string", "performanceRiskLevel": "GOOD", "sellerAccountableDrivers": { "incorrectItemsRate": 0, "arrivedLateRate": 0, "defectiveRate": 0, "damagedRate": 0 }, "nonAccountableDrivers": { "customerChangedMindRate": 0, "miscellaneousRate": 0 }, "recommendations": [ { "recommendation": "string", "moreInfoLink": "string" } ] }, "status": "string"
}

Result

This call returns a summary object with payload (metrics) and status (request state). If successful, the API returns an HTTP status 200 OK with a JSON response. The metrics reflect returns performance summary for orders in the specified time duration.

Rate limits

If you submit too many feeds in a short period of time, you may exceed Walmart’s rate limits and receive HTTP 429 (Too Many Requests) responses. For more details on throttling and best practices, refer to the Rate Limiting Guide.