--- updatedAt: 2026-09-22T19:27:44.000Z --- # Retrieve returns performance summary 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](/reference/getreturns-1). 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. | Value | Description | | :----------------------- | :-------------------------------------------------------------------------------------- | | `GREEN_UP`, `GREEN_DOWN` | A positive change or improved performance compared with the previous reporting window. | | `NEUTRAL` | No change compared with the previous reporting window. | | `RED_UP`, `RED_DOWN` | A negative change or decreased performance compared with the previous reporting window. | # Endpoint ```text GET https://marketplace.walmartapis.com/v3/insights/performance/returns/summary ``` # Query parameters | Parameter | Required | Description | | :--------------- | :------: | :------------------------------------------------------------------------------------------------------------------------- | | `reportDuration` | No | Number of past days included in the reporting window. The default value is `60`. | | `conditionType` | No | Offer condition used to calculate Returns KPI metrics. Allowed values: `NEW`, `ALL`, `RESOLD`. The default value is `ALL`. | 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 curl --request GET \ --url 'https://marketplace.walmartapis.com/v3/insights/performance/returns/summary?reportDuration=60&conditionType=RESOLD' \ -H "WM_SEC.ACCESS_TOKEN: " \ -H "Authorization: Basic " \ -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" ``` ```python import requests url = ( "https://marketplace.walmartapis.com" "/v3/insights/performance/returns/summary" ) headers = { "WM_SEC.ACCESS_TOKEN": "", "Authorization": "Basic ", "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 `` with a valid access token obtained through authentication. * Replace `` 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: ```text conditionType=NEW ``` To retrieve metrics for resold offers: ```text conditionType=RESOLD ``` To retrieve combined new and resold metrics: ```text 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. ```json { "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 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](/us-marketplace/docs/rate-limiting).