Guides
My Account

Retrieve return orders

Call this endpoint to retrieve a list of return orders associated with your account. The API returns details for each return order so you can assess which returns are pending review. Details can include the return order ID, order ID, status, created date, and the items included in the return order.

Note: This example uses only the required parameters for retrieving return orders. For additional filtering options and capabilities, refer to the Returns API Reference.

Endpoint

GET https://marketplace.walmartapis.com/v3/returns

Sample request

This sample shows how to retrieve return orders using the GET /v3/returns endpoint. The request uses the required headers to authenticate and specify JSON as the data format.

curl -X GET "https://marketplace.walmartapis.com/v3/returns" \ -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"

import requests url = "https://marketplace.walmartapis.com/v3/returns" headers = { "Authorization": "Basic <Base64EncodedConsumerKey:ConsumerSecret>", "WM_SVC.NAME": "Walmart Marketplace", "WM_QOS.CORRELATION_ID": "1234567890", "Accept": "application/json", "Content-Type": "application/json"
} response = requests.get(url, headers=headers)
print("Status code:", response.status_code)
print("Response JSON:", response.json())

Modify your code

  1. Replace <Base64EncodedConsumerKey:ConsumerSecret> with your actual Base64-encoded credentials.
  2. Update WM_QOS.CORRELATION_ID with your unique correlation ID if needed.

Sample response

{ "meta": { "totalCount": 40, "limit": 10, "nextCursor": "?sellerId={SellerId}&limit=10&offset=10" }, "returnOrders": [ { "returnOrderId": "{ReturnOrderId}", "customerEmailId": "[email protected]", "customerName": { "firstName": "FirstName", "lastName": "LastName" }, "customerOrderId": "{CustomerOrderId}", "refundMode": "POST_DELIVERY", "returnOrderDate": "YYYY-MM-DDThh:mm:ss.sssZ", "returnType": "REPLACEMENT", "replacementCustomerOrderId": "{ReplacementCustomerOrderId}", "returnByDate": "YYYY-MM-DDThh:mm:ss.sssZ", "totalRefundAmount": { "currencyAmount": 0.00, "currencyUnit": "USD" }, "returnLineGroups": [ { "groupNo": 1, "returnLines": [ { "returnOrderLineNumber": 1 } ], "labels": [ { "labelImageURL": "https://example.com/label.png", "carrierInfoList": [ { "carrierId": "XX", "carrierName": "CarrierName", "serviceType": "ServiceType", "trackingNo": "TRACKINGNUMBER" } ] } ], "returnExpectedFlag": true } ], "returnOrderLines": [ { "returnOrderLineNumber": 1, "salesOrderLineNumber": 1, "returnReason": "DEFECTIVE", "returnDescription": "Description of return", "purchaseOrderId": "{PurchaseOrderId}", "sellerOrderId": "{SellerOrderId}", "purchaseOrderLineNumber": 1, "isReturnForException": true, "exceptionItemType": "EXCEPTION_TYPE", "rechargeReason": "Recharge Reason", "returnCancellationReason": "Cancellation Reason", "item": { "sku": "{SKU}", "condition": "Pre-Owned: Like New", "productName": "Product Name", "itemWeight": { "unitOfMeasure": "POUND", "measurementValue": 0 } }, "charges": [ { "chargeCategory": "PRODUCT", "chargeName": "ItemPrice", "chargePerUnit": { "currencyAmount": 0.00, "currencyUnit": "USD" }, "isDiscount": false, "isBillable": true, "tax": [ { "taxName": "TaxName", "excessTax": { "currencyAmount": 0.00, "currencyUnit": "USD" }, "taxPerUnit": { "currencyAmount": 0.00, "currencyUnit": "USD" } } ], "excessCharge": { "currencyAmount": 0.00, "currencyUnit": "USD" }, "references": [ { "name": "isAdjustment", "value": "false" } ] } ], "unitPrice": { "currencyAmount": 0.00, "currencyUnit": "USD" }, "chargeTotals": [ { "name": "lineUnitPrice", "value": { "currencyAmount": 0.00, "currencyUnit": "USD" } }, { "name": "lineProductTaxes", "value": { "currencyAmount": 0.00, "currencyUnit": "USD" } }, { "name": "lineTotalTaxes", "value": { "currencyAmount": 0.00, "currencyUnit": "USD" } }, { "name": "lineSubTotal", "value": { "currencyAmount": 0.00, "currencyUnit": "USD" } }, { "name": "lineTotal", "value": { "currencyAmount": 0.00, "currencyUnit": "USD" } } ], "currentDeliveryStatus": "NOT_SHIPPED", "currentRefundStatus": "REFUND_INITIATED", "currentTrackingStatuses": [ { "status": "COMPLETED", "statusTime": "YYYY-MM-DDThh:mm:ss.sssZ", "currentRefundStatus": "REFUND_INITIATED", "quantity": { "unitOfMeasure": "EACH", "measurementValue": 0 } }, { "status": "COMPLETED", "statusTime": "YYYY-MM-DDThh:mm:ss.sssZ", "currentRefundStatus": "REFUND_COMPLETED", "quantity": { "unitOfMeasure": "EACH", "measurementValue": 0 } } ], "refundChannels": [ { "refundChannelName": "SELLER_AUTO_REFUND", "quantity": { "measurementValue": 0 } }, { "refundChannelName": "InstantRefund", "quantity": { "measurementValue": 0 } } ], "cancellableQty": 0, "quantity": { "unitOfMeasure": "EACH", "measurementValue": 0 }, "returnExpectedFlag": true, "isFastReplacement": false, "isKeepIt": false, "lastItem": false, "refundedQty": 0, "rechargeableQty": 0, "refundChannel": "SELLER_AUTO_REFUND", "returnTrackingDetail": [ { "sequenceNo": 1, "eventTag": "RETURN_IN_TRANSIT", "eventDescription": "Return in transit", "eventTime": "YYYY-MM-DDThh:mm:ss.sssZ", "references": [ { "name": "ReturnDate", "value": "YYYY-MM-DDThh:mm:ss.sssZ" }, { "name": "SLA for Receiving Items", "value": "X Days" } ] }, { "sequenceNo": 0, "eventTag": "RETURN_INITIATED", "eventDescription": "Return initiated", "eventTime": "YYYY-MM-DDThh:mm:ss.sssZ", "references": [ { "name": "ReturnDate", "value": "YYYY-MM-DDThh:mm:ss.sssZ" }, { "name": "FedexTrackingLink", "value": "https://example.com/fedextrack" } ] } ], "status": "COMPLETED", "statusTime": "YYYY-MM-DDThh:mm:ss.sssZ" } ], "returnChannel": { "channelName": "Seller_Returns" } } ]
}

Result

If successful, the API returns an HTTP status of 200 OK along with a JSON payload that includes meta information such as the total count of return orders and pagination details. Each return order summary provides key data like the return order ID, customer details, refund mode, and important dates. Additionally, item-level information and tracking details are included to give you full visibility into each return.

Next step

Issue a refund for a given return order.

Updated about 15 hours ago