Request a promotions report

Use this report to view all active and upcoming promotions within a timeframe. It lists promotional prices with start and end dates so you can validate setup, track coverage, and measure impact.

Endpoint

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

Sample request with filters

Use rowFilters to scope the file to a date window or specific promotions.

POST https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=PROMOTIONS&reportVersion=v1
Authorization: Bearer <access_token>
WM_QOS.CORRELATION_ID: <guid>
WM_SVC.NAME: Walmart Marketplace
Accept: application/json
Content-Type: application/json { "format": "CSV", "rowFilters": { "promoEffectiveDate": { "from": "2025-12-01", "to": "2026-01-15" }, "promoId": ["PR-1001", "PR-2002"], "sku": ["SKU-123", "SKU-456"] }
}

cURL

curl -X POST \ 'https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=PROMOTIONS&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 '{ "format": "CSV", "rowFilters": { "promoEffectiveDate": { "from": "2025-12-01", "to": "2026-01-15" }, "promoId": ["PR-1001"], "sku": ["SKU-123"] } }'

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.

CSV fields

The downloaded ZIP contains a CSV with the following information. Headers are case sensitive and appear exactly as shown.

Field	Description	Origin
`SKU`	Unique ID of the product.	Seller
`Item ID`	Numeric identifier that uniquely identifies the item.	Walmart
`Product Name`	Name of the product.	Seller
`Product Category`	Category of the product.	Walmart
`Promo ID`	Unique ID of the promotion.	Walmart
`Promo Effective Date`	Date the promotion begins.	Seller
`Promo Expiration Date`	Date the promotion ends.	Seller
`Current Price`	Promotion price of the product.	Seller
`Current Price Currency`	Currency of the promotion price (for example, `USD`).	Seller
`Comparison Price`	Base price of the product without the promotion.	Seller
`Comparison Price Currency`	Currency of the base price.	Seller
`Promotion Type`	One of `Clearance`, `Reduced`, or `Base`.	Seller
`Promotion Status`	One of `Created`, `Updated`, `Activated`, or `Deactivated`.	Walmart

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 filter shape.	Check `reportType`, `reportVersion`, and filter format.
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.