Order refunds summaries

Sellers can use this endpoint to track the percentage of orders that are refunded. Walmart Marketplace requires sellers to maintain refund percentages that are 6% or lower. Else, the Walmart Marketplace may suppress, suspend, or terminate your seller account. You can call the endpoint to specify the number of days (14, 30, 60, 90) of order data to include in metric calculations.

This endpoint uses metrics like cumulative trends, item defective rates, and number of delivered orders that were damaged to calculate your refunds metrics.

The cumulativeRateTrend response parameter uses the statuses in the table below to explain if a trend is a positive or negative change.

Throttling

Request limits: One call per minute per seller. You may receive an HTTP 429 error if you exceed this limit. You can refer to the throttling guide to learn more about the throttling guidelines.

Request example

The endpoint https://marketplace.walmartapis.com/v3/insights/performance/refunds/summary specifies that you are requesting the metrics for the percentage of orders that required a refund.

The following example retrieves the metrics for customer messages from the past 30 days that were responded to within 48 hours of receipt.

reportDuration: Number of days used to calculate the metric. For example, 30.

Encoding for spaces: This request requires encoding if spaces are present in the query. The endpoint uses %20 for spaces.

Before you use the example code, replace the example access token and correlation ID (a randomly generated GUID used to track and debug issues) with your own values.

curl -X 'GET' \ 'https://marketplace.walmartapis.com/v3/insights/performance/refunds/summary?reportDuration=30' \ -H 'accept: application/json' \ -H ‘WM_SEC.ACCESS_TOKEN: eyABCDEFGHI123456789…’ \ -H ‘WM_QOS.CORRELATION_ID: AAAAAAAA-1111-BBBB-2222-CCCC3333DDDD’ \ -H 'WM_SVC.NAME: Walmart Service Name' 

Response example

This API endpoint responds with both a header and a body. The header response provides the details regarding the type of connection to the API server and when it received API call from the seller. The body response contain payload, sellerAccountableDrivers, and nonAccountableDrivers maps containing the various metrics used to calculate the order refunds rate metrics.

nonAccountableDrivers are metrics that will not affect the Seller Performance Standards metrics.

sellerAccountableDrivers are metrics that will affect the Seller Performance Standards metrics.

Response Header

connection: keep-alive content-length: 1087 content-type: application/json date: Tue,25 Feb 2025 22:45:53 GMT keep-alive: timeout=60 vary: Origin,Access-Control-Request-Method,Access-Control-Request-Headers 

Response Body

{ "payload": { "reportDuration": 30, "updatedTimestamp": "2025-02-02T19:49:56Z", "cumulativeRate": 8.8, "cumulativeRateTrend": "GREEN_DOWN", "gmvLoss": 1940, "gmvLossTrend": "GREEN_DOWN", "ordersImpacted": 19, "ordersImpactedTrend": "GREEN_DOWN", "standard": "below 6%", "riskLevel": "Monitor", "sellerAccountableDrivers": { "incorrectItemsRate": 6.98, "arrivedLateRate": 1.03, "defectiveRate": 0.72, "damagedRate": 0.12, "lostRate": 0 }, "nonAccountableDrivers": { "customerChangedMindRate": 20.97, "miscellaneousRate": 0.36, "undeliveredRate": 0 }, "recommendations": [ { "recommendation": "Meet customer expectations", "moreInfoLink": "https://sellerhelp.walmart.com/seller/s/guide?language=en_US&article=000007440#Overview" }, { "recommendation": "Monitor your assortment", "moreInfoLink": "https://sellerhelp.walmart.com/seller/s/guide?language=en_US&article=000007440#Overview" } ] }, "status": "OK"
} 

Next steps

This GET Refunds summary overview guide explains the basic parameters required to call this endpoint. You can refer to the full Reference guide to learn about optional parameters.