Call this endpoint to get a consolidated snapshot of your returns performance for the last N days. The default reporting window is 60 days. The API aggregates return rate, GMV loss, impacted orders, risk level, primary drivers, and actionable recommendations, including trend signals.

Use the optional conditionType query parameter to retrieve Returns KPI metrics for new offers, resold offers, or both. Allowed values are NEW, RESOLD, and ALL.

To retrieve metrics for a specific offer condition, explicitly pass conditionType=NEW or conditionType=RESOLD. When conditionType is omitted or left blank, the API defaults to ALL, which combines metrics for new and resold offers.

This page describes an example using the required headers and common query parameters to retrieve a 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 whether a trend represents a positive or negative change. The trend compares the metric with the previous reporting window ending the day before.

Endpoint

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

Query parameters

The conditionType values operate as follows:

• NEW returns metrics calculated from orders for new offers.
• RESOLD returns metrics calculated from orders for resold offers.
• ALL returns combined metrics for new and resold offers.

The response includes conditionType to identify the offer condition represented by the returned metrics.

The response returns "conditionType": "RESOLD" only when the seller is enrolled in the Resold category and has orders for resold offers.

Sample request

Use this sample request to retrieve the returns performance summary for resold offers during the past 60 days.

curl --request GET \ --url 'https://marketplace.walmartapis.com/v3/insights/performance/returns/summary?reportDuration=60&conditionType=RESOLD' \ -H "WM_SEC.ACCESS_TOKEN: <ACCESS_TOKEN>" \ -H "Authorization: Basic <BASE64_CLIENT_ID_AND_CLIENT_SECRET>" \ -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": "<ACCESS_TOKEN>", "Authorization": "Basic <BASE64_CLIENT_ID_AND_CLIENT_SECRET>", "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, "conditionType": "RESOLD",
} response = requests.get( url, headers=headers, params=params, timeout=60,
) response.raise_for_status() print(response.status_code)
print(response.json())

Modify your code

• Use a unique WM_QOS.CORRELATION_ID for each request.
• Replace <ACCESS_TOKEN> with a valid access token obtained through authentication.
• Replace <BASE64_CLIENT_ID_AND_CLIENT_SECRET> with your encoded credentials.
• Add conditionType to request metrics for a specific offer condition.
  • Use only NEW, ALL, or RESOLD.
  • Omit conditionType, or leave it blank, to use the default value of ALL.

To retrieve metrics for new offers:

conditionType=NEW

To retrieve metrics for resold offers:

conditionType=RESOLD

To retrieve combined new and resold metrics:

conditionType=ALL

Sample response

This sample response summarizes returns performance for resold offers during the last 60 days. It includes the offer condition used to calculate the metrics, overall return rate, GMV loss, impacted orders, trend indicators, risk level, primary drivers, and recommendations.

• nonAccountableDrivers are metrics that do not affect Seller Performance Standards.
• sellerAccountableDrivers are metrics that affect Seller Performance Standards.
• If an API response includes a single cumulative rate, interpret it as the seller-accountable rate.
• When a metrics API includes both a seller-accountable rate and an overall or cumulative rate, the second value represents the total rate.
• In this context, overall and cumulative are equivalent and may be used interchangeably.

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

Note: The API returns "conditionType": "RESOLD" only when the seller is enrolled in the Resold category and has orders for resold offers.

Result

This call returns a summary object containing payload, which contains the metrics, and status, which identifies the request state.

When successful, the API returns HTTP 200 OK with a JSON response. The metrics reflect returns performance for the specified reporting duration and offer condition.

The returned conditionType identifies which metrics are represented:

• NEW indicates metrics for new offers.
• RESOLD indicates metrics for eligible resold offers.
• ALL indicates combined metrics for new and resold offers.

When conditionType is omitted or blank, the API defaults to ALL.

The endpoint can also return:

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

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.