--- updatedAt: 2026-07-06T19:53:36.000Z --- # Get Returns Performance Metrics Returns the seller's returns performance summary for the past N days (defaults to 60 days). Includes cumulative return rate, impacted orders, risk level, drivers, and recommendations. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Insights Management", "version": "1.0", "description": "The Insights Management API provides sellers with actionable information to optimize their listings:\n* Sellers can locate best-selling items with Trending Items API so they can add those to their catalog of item offerings. \n* Sellers can find out reasons why items go unpublished, fix the issue and republish those items.\n* Sellers can use Listing Quality APIs to gather listing quality metrics about their items and identify any issues that they can fix.\n* Sellers can obtain their overall Listing Quality score, and locate any categories that show items with listing quality issues." }, "x-readme": { "samples-languages": [ "shell" ], "proxy-enabled": false }, "servers": [ { "url": "https://marketplace.walmartapis.com", "description": "Production URL" }, { "url": "https://sandbox.walmartapis.com", "description": "Sandbox URL" } ], "security": [ { "accessToken": [] } ], "paths": { "/v3/insights/performance/returns/summary": { "get": { "tags": [ "Insight" ], "summary": "Get Returns Performance Metrics", "description": "Returns the seller's returns performance summary for the past N days (defaults to 60 days). Includes cumulative return rate, impacted orders, risk level, drivers, and recommendations.", "externalDocs": { "description": "View Guide", "url": "https://sellerhelp.walmart.com/s/guide?language=en_US&article=000007175" }, "operationId": "getReturns", "parameters": [ { "name": "reportDuration", "in": "query", "description": "Number of past days to include in the report duration window. If omitted, default value of 60 days is used.", "required": false, "schema": { "type": "integer", "format": "int32", "default": 60 } }, { "name": "conditionType", "in": "query", "description": "Refers to `NEW` or `RESOLD` condition type. If omitted, default value is `ALL`.", "required": false, "schema": { "type": "string", "default": "ALL", "enum": [ "ALL", "NEW", "RESOLD" ] } }, { "in": "header", "name": "Authorization", "description": "Basic authorization header. Base 64 encodes the Client ID and Client Secret retrieved in step two of the integration steps.", "required": true, "schema": { "type": "string" }, "example": "Basic YzcyOTFjNmItNzI5MC00...." }, { "in": "header", "name": "WM_SEC.ACCESS_TOKEN", "description": "Access token obtained from the Token API. This is required for authenticating requests to Walmart Marketplace APIs.", "required": true, "schema": { "type": "string" }, "example": "eyJraWQiOiIxNWNhNGIyYi0yODVjLTQ0ZDUtYmExNC05ZDk1NTlkZmUwNjgiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0...." }, { "in": "header", "name": "WM_CONSUMER.CHANNEL.TYPE", "description": "A unique ID to identify the consumer request by channel. Use the Consumer Channel Type received during onboarding.", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "WM_QOS.CORRELATION_ID", "description": "A unique ID that identifies each API call and is used to track and debug issues. Use a randomly generated GUID for this ID.", "required": true, "schema": { "type": "string" }, "example": "b3261d2d-028a-4ef7-8602-633c23200af6" }, { "in": "header", "name": "WM_SVC.NAME", "description": "Specifies the name of the Walmart service being called.", "required": true, "schema": { "type": "string" }, "example": "Walmart Marketplace" } ], "responses": { "200": { "description": "Successful operation. Returns performance metrics and insights for the requested reporting period.", "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "type": "object", "properties": { "reportDuration": { "type": "integer", "description": "Number of past days used to compute the metrics.", "format": "int32" }, "updatedTimestamp": { "type": "string", "description": "Timestamp when metrics were last calculated, in ISO 8601 format.", "example": "2025-12-01T06:30:45Z" }, "cumulativeRate": { "type": "number", "description": "Cumulative returns rate for the requested reporting period.", "format": "float" }, "cumulativeRateTrend": { "type": "string", "description": "Cumulative returns rate trend.", "enum": [ "GREEN_UP", "GREEN_DOWN", "RED_UP", "RED_DOWN", "NEUTRAL" ] }, "gmvLoss": { "type": "number", "description": "Estimated gross merchandise value (GMV) loss for the reporting period.", "format": "float" }, "gmvLossTrend": { "type": "string", "description": "Trend indicator for GMV loss.", "enum": [ "GREEN_UP", "GREEN_DOWN", "RED_UP", "RED_DOWN", "NEUTRAL" ] }, "ordersImpacted": { "type": "integer", "description": "Number of orders impacted by returns in the reporting period.", "format": "int32" }, "ordersImpactedTrend": { "type": "string", "description": "Trend indicator for impacted orders.", "enum": [ "GREEN_UP", "GREEN_DOWN", "RED_UP", "RED_DOWN", "NEUTRAL" ] }, "performanceStandard": { "type": "string", "description": "Maximum allowed cumulative returns rate as defined by Walmart performance standards." }, "conditionType": { "type": "string", "description": "Type of Return metric. ALL, NEW or RESOLD", "enum": [ "ALL", "NEW", "RESOLD" ] }, "performanceRiskLevel": { "type": "string", "description": "Risk level as defined by Walmart performance standards.", "enum": [ "GOOD", "MONITOR", "URGENT" ] }, "sellerAccountableDrivers": { "type": "object", "properties": { "incorrectItemsRate": { "type": "number", "description": "Returns rate due to incorrect items.", "format": "float" }, "arrivedLateRate": { "type": "number", "description": "Returns rate due to late arrival of item.", "format": "float" }, "defectiveRate": { "type": "number", "description": "Returns rate due to defective items.", "format": "float" }, "damagedRate": { "type": "number", "description": "Returns rate due to damaged items.", "format": "float" } }, "description": "Seller accountable drivers that impact the returns rate." }, "nonAccountableDrivers": { "type": "object", "properties": { "customerChangedMindRate": { "type": "number", "description": "Returns rate due to customer changed mind.", "format": "float" }, "miscellaneousRate": { "type": "number", "description": "Returns rate due to miscellaneous items.", "format": "float" } }, "description": "Non-accountable drivers that impact the returns rate." }, "recommendations": { "type": "array", "description": "Actionable recommendations to help decrease the returns rate.", "items": { "type": "object", "properties": { "recommendation": { "type": "string", "description": "The recommended action." }, "moreInfoLink": { "type": "string", "description": "The URL for information or guidance about the recommended action.", "format": "url" } }, "description": "Recommendations to decrease the returns rate." } } } }, "status": { "type": "string" } } } } } }, "204": { "description": "No summary content found for the seller." }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code of the response. \n", "example": "500" }, "description": { "type": "string", "description": "Description of error.\n\n", "example": "HTTP 500 Some error occurred" }, "severity": { "type": "string", "description": "Severity of Error.\n\nExample: ERROR\n", "example": "ERROR" }, "category": { "type": "string", "description": "Category of error.\n\nExample: DATA\n", "example": "REQUEST" }, "causes": { "type": "array", "description": "Causes of error.", "example": [], "items": { "type": "string", "description": "Causes of error.", "example": "[]" } }, "errorIdentifiers": { "type": "object", "description": "Error Identifiers of the error.", "example": {} } } } } } } } } } }, "components": { "securitySchemes": { "accessToken": { "type": "apiKey", "in": "header", "name": "WM_SEC.ACCESS_TOKEN", "description": "Access token required for authenticating API requests.\n\nTo obtain a token, call `POST https://marketplace.walmartapis.com/v3/token` with your client ID and client secret using the client credentials grant type. Refer to the [Token API documentation](https://developer.walmart.com/us-marketplace/docs/get-an-access-token) for details.\n\nPass the resulting token in the `WM_SEC.ACCESS_TOKEN` header with every API request." } } } } ```