Request a buy box insights report

Use this report to improve offer competitiveness. It shows which SKUs are winning or losing the Buy Box and compares your price and ship price to the winning offer so you can make targeted changes.

Endpoint

POST https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=BUYBOX&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=BUYBOX&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=BUYBOX&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. Headers are case sensitive and appear exactly as shown.

Column name	Description
`SKU`	Alphanumeric unique ID specified by the seller for each item.
`Item ID`	Walmart item ID on Walmart.com.
`Product Name`	Name of the item.
`Product Category`	Category of the item.
`Seller Item Price`	Your current item price.
`Seller Ship Price`	Your current shipping price.
`isSellerBuyBoxWinner`	`Yes` if you are the Buy Box winner for the SKU, otherwise `No`.
`BuyBox Item Price`	The Buy Box winner’s item price.
`BuyBox Ship Price`	The Buy Box winner’s shipping price.

Most values reflect the state at the time the file was generated.

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.