Submit a claim

Call this endpoint to submit a shipment-protection claim for a Ship with Walmart (SWW) label that is lost in transit, lost after delivery, or damaged.

Note: This page shows only the required parameters for a basic claim submission. For optional fields, file-upload details, and advanced workflows, see the Shipment Protection API reference.

Endpoint

POST https://marketplace.walmartapis.com/v3/claims/shipment-protection/claim

Sample request

This request files a claim for three damaged items on a purchase-order line:

curl -X POST "https://marketplace.walmartapis.com/v3/claims/shipment-protection/claim" \ -H "Authorization: Basic <Base64EncodedConsumerKey:ConsumerSecret>" \ -H "WM_SVC.NAME: Walmart Marketplace" \ -H "WM_QOS.CORRELATION_ID: 1234567890" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "purchaseOrderNo": "RAPMOCK1729803026938", "purchaseOrderLineNo": "1", "salesOrderNo": "RAPMOCK1729803026883", "salesOrderLineNo": "1", "fulfillerLineId": "1", "quantity": 3, "returnOrderId": "136900073772361154", "claimType": "DAMAGED", "notes": "claim submission notes." }' 

import requests url = "https://marketplace.walmartapis.com/v3/claims/shipment-protection/claim" payload = { "purchaseOrderNo": "RAPMOCK1729803026938", "purchaseOrderLineNo": "1", "salesOrderNo": "RAPMOCK1729803026883", "salesOrderLineNo": "1", "fulfillerLineId": "1", "quantity": 3, "returnOrderId": "136900073772361154", "claimType": "DAMAGED", "notes": "claim submission notes."
} headers = { "Authorization": "Basic <Base64EncodedConsumerKey:ConsumerSecret>", "WM_SVC.NAME": "Walmart Marketplace", "WM_QOS.CORRELATION_ID": "1234567890", "Accept": "application/json", "Content-Type": "application/json"
} response = requests.post(url, headers=headers, json=payload)
print("Status code:", response.status_code)
print("Response JSON:", response.json())

Modify your code

1. Replace the purchase-order, sales-order, and return-order IDs with your values.
2. Set claimType to DAMAGED, LIT, or LAD as appropriate.
3. Adjust quantity to match the number of items affected.
4. Insert your Base64-encoded credentials in the Authorization header.
5. Use a unique WM_QOS.CORRELATION_ID to trace your request.

Sample response

{ "data": { "claimNumber": "100001234", "message": "Claim submitted successfully" }
}

Result

If successful, the API returns an HTTP 200 OK status with the generated claimNumber and a confirmation message. Use this claim number to track status changes, add documents, or download claim files.

Next steps

• Track your claim
  Call GET /v3/claims/shipment-protection/claim/{claimNumber} to monitor status changes from INITIATED > IN_REVIEW > APPROVED or REJECTED.
• Watch for action-required claims
  If you manage many claims, poll GET /v3/claims/shipment-protection?claimsGroup=ACTION_NEEDED or subscribe to claim event notifications.
• Provide additional information when requested
  When the status is NEED_INFO, respond with PATCH /v3/claims/shipment-protection/claim/{claimNumber} to upload supporting documents or notes.
• Retrieve the audit trail or documents
  Use GET /history to see all status changes, or POST /documents to download uploaded files for reconciliation.