Request a return item overrides report

Use this report to audit item-level return rule overrides. It lists SKUs where returns behavior differs from your global settings so you can confirm exceptions, reduce abuse, and align costs.

Endpoint

POST https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=RETURN_ITEM_OVERRIDES&reportVersion=v1

The request body is optional. When the request is accepted, the API returns a requestId you can use to track status and download the file.

Sample request

POST https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=RETURN_ITEM_OVERRIDES&reportVersion=v1
Authorization: Bearer <access_token>
WM_QOS.CORRELATION_ID: <guid>
WM_SVC.NAME: Walmart Marketplace
Accept: application/json
Content-Type: application/json {}

cURL

curl -X POST \ 'https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=RETURN_ITEM_OVERRIDES&reportVersion=v1' \ -H 'Authorization: Bearer <access_token>' \ -H 'WM_QOS.CORRELATION_ID: <guid>' \ -H 'WM_SVC.NAME: Walmart Marketplace' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{}'

Use a new GUID for each call. Keep the requestId to track status and download the report.

Track and download

Check status until the report is ready.
```
GET https://marketplace.walmartapis.com/v3/reports/reportRequests/{requestId}
```
Status values: RECEIVED, INPROGRESS, READY, ERROR.

Download once status is READY.

GET https://marketplace.walmartapis.com/v3/reports/downloadReport?requestId={requestId}

If you prefer not to poll, subscribe to Report status notifications and receive a callback when the file is ready.

Filters

Filters are not supported for this report. The file always includes all rows available to your account. After download, use your CSV tool to filter by SKU or columns as needed.

CSV fields

The file contains one row per SKU with an override. Headers are case sensitive and appear exactly as shown.

Field	Description	Origin
`SKU`	Unique identifier for the item.	Seller
`Keep It`	Allow customers to keep the item but still receive a refund. Valid values: `Yes`, `No`, or blank.	Seller
`Return Restricted`	Item is restricted for return. Valid values: `Yes`, `No`, or blank.	Seller
`Restriction Reason`	Reason for restricting the item for return.	Seller
`Return Center (Alias)`	Return center alias configured by the seller.	Seller
`Publish Status`	Whether the item is published on Walmart.com.	Walmart

Your file is the source of truth for the final header list. Some programs may include additional columns.

Error handling

Common failures when requesting or downloading reports:

HTTP	Code (example)	When it happens	How to fix
400	`MISSING_REQUEST_PARAM`	Required parameter missing (for example, `reportType`).	Add the missing parameter and retry.
400	`INVALID_REQUEST`	Unsupported `reportType` or invalid shape.	Check `reportType` and `reportVersion`.
401	`UNAUTHORIZED`	Invalid or missing OAuth token.	Refresh your token and retry.
404	`CONTENT_NOT_FOUND`	Unknown or expired `requestId`.	Verify the `requestId` and retention.
429	`RATE_LIMIT_EXCEEDED`	Too many requests.	Back off and retry with jitter.
500	`INTERNAL_ERROR`	Unexpected error.	Retry GET calls; contact support.