Request a delivery defect report

Use this report to identify late or missing deliveries that drive customer contacts. It lists order lines with promised dates, actual delivery dates, and shipment details so you can find regional or carrier hotspots and fix root causes.

Endpoint

POST https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=DELIVERY_DEFECT&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=DELIVERY_DEFECT&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 report to a specific time window, carrier, or region.

POST https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=DELIVERY_DEFECT&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": { "orderPlacedDt": { "from": "2025-11-01", "to": "2025-11-30" }, "carrier": ["USPS", "FedEx", "UPS"], "destinationState": ["CA", "TX", "FL"] }
}

cURL

curl -X POST \ 'https://marketplace.walmartapis.com/v3/reports/reportRequests?reportType=DELIVERY_DEFECT&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": { "orderPlacedDt": { "from": "2025-11-01", "to": "2025-11-30" }, "carrier": ["USPS"], "destinationState": ["CA"] } }'

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 file contains one row per affected order line. Headers are case sensitive and appear exactly as shown.

Field	Description	Origin
`orderPlacedDt`	The date when the order was placed.	Walmart
`actualDeliveryDate`	The date when the item was delivered.	Walmart
`cancelDate`	The date when the item was cancelled.	Seller
`destinationState`	The two letter code representing the state in the shipping address (for example, `VA`, `CA`, `WA`).	Walmart
`estimatedDeliveryDate`	The estimated delivery date of the purchase order.	Walmart/Seller
`salesOrder`	Unique customer order number for the Walmart purchase.	Walmart
`returnDate`	The date when the return request was placed.	Walmart
`trackingNum`	The tracking number of the order.	Seller
`carrier`	The carrier used to ship the order to the customer.	Seller
`catlgItemId`	Unique item ID.	Walmart
`returnReason`	The reason the item was returned.	Walmart
`offerId`	Unique identifier that is a combination of SKU and partnerId.	Walmart
`poNum`	Purchase order number that represents Walmart placing the order with the seller.	Walmart
`legacySlrId`	Unique seller ID.	Walmart
`defectType`	The type of defect for the item. For Delivery Defect reports, the value is `OTD` (on-time delivery).	Walmart/Seller
`cancelReason`	The reason the item was cancelled.	Walmart/Seller

Some programs include additional columns for region, postal code, or ship node. Your file is the source of truth for the final header list.

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.