Request a Buy Box insights report

To get the Buy Box Report, call GET /v3/getReport and specify BUY BOX for the type query parameter (for example: GET BuyBox.

The Buy Box report provides the most recent data about Buy Box winning prices and other insights about items to give you information about the current Buy Box prices for items in your catalog and other insights, so you can make decisions about what prices to set if you would like to win the Buy Box.

Filters are not supported, so when you generate the report, you will receive all column data. However, you can filter the columns post-download with your CSV file. The report returns data on all your current catalog items.

You can see insights about item such as:

• Which items in your catalog are currently winning or losing the Buy Box
• Buy Box data for the winning offer, including the winning offer price and ship price for an item
• What is your current price and shipping price for an item

BuyBox insight report columns

Most of the columns are self-explanatory, such as SKU, Is Seller Buy Box Winner (Yes/No).  This table provides descriptions for the insight’s columns in the report.

Most data in the report is real-time data. Once the report is available, you can download it to return all the information associated with your items that are set up on Walmart’s platform.

Note:  All example API calls shown assume the Walmart API endpoint:

https://marketplace.walmartapis.com

Step 1:  Request the Buy Box insights report

To request an item report, call the Create Report Request API.

For example: call v3/reports/reportRequests?reportType=BUYBOX&reportVersion=v1

Specify values for all required parameters:

reportType – Specify which report you want to request (e.g. reportType=BUYBOX).

reportVersion – Specify report version (for example, reportVersion=v1)

Upon success, the API call returns a requestID that you can use to find out if the report is ready for download and status of the request (for example, RECEIVED or INPROGRESS).  It also returns values for requestSubmissionDate in UTC format: YYY-MM-DDTHH:mmssZ.

You can also set up a Notification to trigger once the report status is READY.  To set up a notification, see Notifications (/doc/us/mp/us-mp-notifications/).

Step 2:  Get report availability status:

To find out if the report is ready for download, call Report Request Status API to retrieve report request status. When status is READY, you can download the report. The API can only retrieve details of requests created in the past 30 days.

For example, call v3/reports/reportRequests?{requestID} with the request ID.

Upon success, this call retrieves the status of the specified request ID (for example, SUBMITTED, INPROGRESS, READY, or ERROR).

Step 3:  (Optional) Subscribe to an event notification

To get notified when the requested report is ready to download, create a Webhook notification. When the report status changes to READY, this triggers the notification.

For steps to subscribe, see Notifications. In addition to other required parameters, make sure to set resourceName to REPORTS, eventType to REPORT_STATUS, eventVersion to V1.

For example:

“resourceName”: “REPORTS”

“eventType”: “REPORT_STATUS”

“eventVersion”: “V1”

"Description”: “Notification for report status”

Step 4: (Optional) Get a list of all requests

To get a list of all report requests in the last 30 days, call the Get All Report RequestsAPI.  Request log does not continue to store requests past 30 days.

For example, call /v3/reports/reportRequests directly to retrieve a list of all requests.

(Optional):  You can also filter the list with these query parameters:

reportType – Specify a specific type of report only, for example reportTyle=BUYBOX for Buy Box report.

requestID – Specify a single request ID to return.

requestStatus – Request only report requests with one status to be returned: RECEIVED, INPROGRESS, READY, or ERROR. For example, requestStatus=READY.

requestSubmissionStartDate – Specify a range of report requests and provide start date.

requestSubmissionEndDate – Specify a range of report requests and provide end date.

Example:  Request all reports that are ready

If you want to return all current report requests that are currently ready, you can call:

/v3/reports/reportRequests?requestStatus=READY

Step 5:  Download the report URL

To download a report you requested, call the Download Report URL API and specify the requestID sent by the report status notification, or from a status API call.

For example, call /v3/reports/downloadReport?requestID={requestID}

Upon success, you will receive the URL to download the report along with the URL expiration time:

downloadURL – the URL to download the report.

downloadURLExpirationTime – the download URL expiration time.

To avoid errors, make sure to check these situations don’t apply to your request:

The request has expired. In this case, the report is no longer available.

If the report is not yet available, check to see the status is not INPROGRESS.

Could be either system error, or has data errors.

If the requestID is invalid. Make sure you have the correct ID, or that it hasn’t expired after 30 days.

Troubleshooting and error codes

If you get failures, here are some hints for how to solve these possible errors. Notice there are several reasons why you might get INVALID_REQUEST_PARAM error, depending on which API you call, and which parameters are required for that API.

Helpful Links

Seller Center

Supplier Center

Sandbox API

Terms and Conditions