Cancel orders

Call this endpoint to cancel one or more order lines for a specific order. Use this action when you are unable to fulfill certain items or need to cancel an order partially or entirely. This endpoint updates the order line status to Cancelled and returns the updated order details.

Note:

  • Make sure you only cancel order lines that have not been shipped.
  • Orders fulfilled by Walmart Fulfillment Services (WFS) can't be cancelled using this endpoint. Use the Cancel customer order for WFS item endpoint instead.

Endpoint

POST https://marketplace.walmartapis.com/v3/orders/{purchaseOrderId}/cancel

Sample request

curl -X POST "https://marketplace.walmartapis.com/v3/orders/{purchaseOrderId}/cancel" \ -H "Authorization: Basic <Base64EncodedClientID:ClientSecret>" \ -H "WM_SVC.NAME: Walmart Marketplace" \ -H "WM_QOS.CORRELATION_ID: 0123456" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "orderCancellation": { "orderLines": { "orderLine": [ { "orderLineStatuses": { "orderLineStatus": [ { "status": "Cancelled", "cancellationReason": "CUSTOMER_REQUESTED_SELLER_TO_CANCEL", "statusQuantity": { "unitOfMeasurement": "EACH" } } ] } } ] } } }'
import requests url = "https://marketplace.walmartapis.com/v3/orders/{purchaseOrderId}/cancel" headers = { "Authorization": "Basic <Base64EncodedClientID:ClientSecret>", "WM_SVC.NAME": "Walmart Marketplace", "WM_QOS.CORRELATION_ID": "0123456", "Accept": "application/json", "Content-Type": "application/json"
} data = { "orderCancellation": { "orderLines": { "orderLine": [ { "orderLineStatuses": { "orderLineStatus": [ { "status": "Cancelled", "cancellationReason": "CUSTOMER_REQUESTED_SELLER_TO_CANCEL", "statusQuantity": { "unitOfMeasurement": "EACH" } } ] } } ] } }
} response = requests.post(url, headers=headers, json=data)
print(response.json())

Note: You can cancel specific order lines by specifying their orderLine. For a full order cancellation, include all order lines in the request.

Modify your code

  • Replace {purchaseOrderId} in the endpoint URL with the actual order ID you want to cancel.
  • Substitute <Base64EncodedClientID:ClientSecret> with your Base64-encoded credentials.
  • Update WM_QOS.CORRELATION_ID with a unique value for tracking your request.
  • Adjust the orderCancellation payload if you need to cancel additional order lines or specify a different cancellation reason.

Cancellation reason codes

To cancel an order line, you must include a valid cancellationReason value. The reason you choose helps Walmart understand why the item cannot be fulfilled and may affect future item visibility or fraud evaluation.

Refer to the Cancel order lines API reference for the full list.

cancellationReasonWhen to use it
CUSTOMER_REQUESTED_SELLER_TO_CANCELThe customer asked to cancel the item.
SELLER_CANCEL_OUT_OF_STOCKThe item is out of stock. Walmart may hide the item from listings until inventory is replenished.
SELLER_CANCEL_PRICING_ERRORThere’s a pricing error, such as a mismatch between the listed price and what was intended.
SELLER_CANCEL_ADDRESS_NOT_SERVICEABLEYou or your carrier can’t deliver to the customer’s address.
SELLER_CANCEL_FRAUD_STOP_SHIPMENTYou’ve confirmed the order is fraudulent. If you're unsure, contact the Walmart Risk Prevention team (see the API Reference).

Note: If the cancellation reason does not match the situation, Walmart may restrict or flag your listings.

Sample response

{ "order": { "purchaseOrderId": "0123456789", "customerOrderId": "ABCDEFGHIJ", "customerEmailId": "[email protected]", "orderType": "PREORDER", "orderDate": 1476387173000, "shippingInfo": { "phone": "0123456789", "estimatedDeliveryDate": 1479798000000, "estimatedShipDate": 1476424800000, "methodCode": "Standard", "postalAddress": { "name": "Customer Name", "address1": "123 Cancel St", "address2": "Apt 101", "city": "CITY", "state": "STATE", "postalCode": "ZIPCODE", "country": "COUNTRY", "addressType": "RESIDENTIAL" } }, "orderLines": { "orderLine": [ { "lineNumber": "1", "item": { "productName": "Example Product Name", "sku": "SKU12345" }, "charges": { "charge": [ { "chargeType": "PRODUCT", "chargeName": "ItemPrice", "chargeAmount": { "currency": "USD", "amount": 0 }, "tax": { "taxName": "Tax1", "taxAmount": { "currency": "USD", "amount": 0 } } }, { "chargeType": "SHIPPING", "chargeName": "Shipping", "chargeAmount": { "currency": "USD", "amount": 0 }, "tax": { "taxName": "Tax2", "taxAmount": { "currency": "USD", "amount": 0 } } } ] }, "orderLineQuantity": { "unitOfMeasurement": "EACH", "amount": "1" }, "statusDate": 1481755720000, "orderLineStatuses": { "orderLineStatus": [ { "status": "Cancelled", "statusQuantity": { "unitOfMeasurement": "EACH", "amount": "1" } } ] } } ] } }
}

Result

If successful, the API returns an HTTP status: 200 OK along with a JSON object showing the updated order details. The specified order lines will now have a Cancelled status, indicating that those items will no longer be fulfilled.