Get returns

The Walmart Marketplace Get returns API allows sellers to retrieve return order information. The API returns details for each return order so you can assess which returns are pending review.

Endpoint

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

Function

Use this API to get return information, such as:

Return order ID
Order ID
Status
Created date
Items in the return order

Sample request

curl --request GET \ --url 'https://marketplace.walmartapis.com/v3/returns?limit=10' \ --header 'accept: application/json'

Modify your code

Before sending the request, verify the API endpoint, header and authentication credentials.

Sample response

200

{ "meta": { "totalCount": 40, "limit": 10, "nextCursor": "?sellerId=151&limit=10&offset=10" }, "returnOrders": [ { "returnOrderId": "103738048909818825", "customerEmailId": "[email protected]", "customerName": { "firstName": "Jane", "lastName": "Doe" }, "customerOrderId": "1234567891234", "refundMode": "POST_DELIVERY", "returnOrderDate": "2019-02-21T01:01:08.000Z", "returnType": "REPLACEMENT", "replacementCustomerOrderId": "1234567891234", "returnByDate": "2019-03-23T01:01:06.000Z", "totalRefundAmount": { "currencyAmount": 127.45, "currencyUnit": "USD" }, "returnLineGroups": [ { "groupNo": 1, "returnLines": [ { "returnOrderLineNumber": 1 } ], "labels": [ { "labelImageURL": "https://i5.walmartimages.com/asr/0a0c7462-7a85-4d3d-b7cf-91738b6883d4_1.c2c4f7b05e1cfe67910134779aa7c571.png", "carrierInfoList": [ { "carrierId": "11", "carrierName": "FEDEX", "serviceType": "FedEx Ground", "trackingNo": "785611449666" } ] } ], "returnExpectedFlag": true } ], "returnOrderLines": [ { "returnOrderLineNumber": 1, "salesOrderLineNumber": 1, "returnReason": "DEFECTIVE", "returnDescription": "Poor quality", "purchaseOrderId": "4790210558890", "sellerOrderId": "123", "purchaseOrderLineNumber": 1, "isReturnForException": true, "exceptionItemType": "HAZMAT/OTHER/FREIGHT", "rechargeReason": "Recharge Reason", "returnCancellationReason": "Cancellation Reason", "item": { "sku": "ANTL_GDL-0700", "condition": "Pre-Owned: Like New", "productName": "Antlion Audio ModMic Wireless Attachable Boom Microphone", "itemWeight": { "unitOfMeasure": "POUND", "measurementValue": 5 } }, "charges": [ { "chargeCategory": "PRODUCT", "chargeName": "ItemPrice", "chargePerUnit": { "currencyAmount": 119.95, "currencyUnit": "USD" }, "isDiscount": false, "isBillable": true, "tax": [ { "taxName": "Tax1", "excessTax": { "currencyAmount": 0, "currencyUnit": "USD" }, "taxPerUnit": { "currencyAmount": 7.5, "currencyUnit": "USD" } } ], "excessCharge": { "currencyAmount": 0, "currencyUnit": "USD" }, "references": [ { "name": "isAdjustment", "value": "false" } ] } ], "unitPrice": { "currencyAmount": 119.95, "currencyUnit": "USD" }, "chargeTotals": [ { "name": "lineUnitPrice", "value": { "currencyAmount": 119.95, "currencyUnit": "USD" } }, { "name": "lineProductTaxes", "value": { "currencyAmount": 7.5, "currencyUnit": "USD" } }, { "name": "lineTotalTaxes", "value": { "currencyAmount": 8.75, "currencyUnit": "USD" } }, { "name": "lineSubTotal", "value": { "currencyAmount": 119.95, "currencyUnit": "USD" } }, { "name": "lineTotal", "value": { "currencyAmount": 127.45, "currencyUnit": "USD" } }, { "name": "lineDutyCharges", "value": { "currencyAmount": 1.25, "currencyUnit": "USD" } }, { "name": "lineTaxesAndOtherFees", "value": { "currencyAmount": 8.75, "currencyUnit": "USD" } } ], "currentDeliveryStatus": "NOT_SHIPPED", "currentRefundStatus": "REFUND_INITIATED", "currentTrackingStatuses": [ { "status": "COMPLETED", "statusTime": "2023-06-22T02:20:51.000Z", "currentRefundStatus": "REFUND_INITIATED", "quantity": { "unitOfMeasure": "EACH", "measurementValue": 2 } }, { "status": "COMPLETED", "statusTime": "2023-06-22T02:20:51.000Z", "currentRefundStatus": "REFUND_COMPLETED", "quantity": { "unitOfMeasure": "EACH", "measurementValue": 1 } } ], "refundChannels": [ { "refundChannelName": "SELLER_MANUAL_REFUND", "quantity": { "measurementValue": 2 } }, { "refundChannelName": "InstantRefund", "quantity": { "measurementValue": 1 } } ], "cancellableQty": 0, "quantity": { "unitOfMeasure": "EACH", "measurementValue": 3 }, "returnExpectedFlag": true, "isFastReplacement": false, "isKeepIt": false, "lastItem": false, "refundedQty": 1, "rechargeableQty": 0, "refundCoveredBy": "SELLER_AUTO_REFUND", "returnTrackingDetail": [ { "sequenceNo": 1, "eventTag": "RETURN_IN_TRANSIT", "eventDescription": "A MARKET_PLACE Return in Transit", "eventTime": "2019-02-23T00:46:11.000Z", "references": [ { "name": "ReturnDate", "value": "2019-02-21T01:01:08.000Z" }, { "name": "SLA for Receiving Items", "value": "7 Days" } ] }, { "sequenceNo": 0, "eventTag": "RETURN_INITIATED", "eventDescription": "Return initiated for MARKET_PLACE", "eventTime": "2019-02-21T01:01:08.000Z", "references": [ { "name": "ReturnDate", "value": "2019-02-21T01:01:08.000Z" }, { "name": "FedexTrackingLink", "value": "https://www.fedex.com/apps/fedextrack/?tracknumbers=785611449666" } ] } ], "status": "COMPLETED", "statusTime": "2019-03-02T05:45:45.000Z" } ], "returnChannel": { "channelName": "IN_STORE" } }, { "returnOrderId": "330050624216470154", "customerEmailId": "[email protected]", "customerName": { "firstName": "mam", "lastName": "tha" }, "customerOrderId": "100000276630999", "returnOrderDate": "2024-08-22T11:11:41.000Z", "returnByDate": "2024-09-21T11:11:41.000Z", "refundMode": "INSTANT", "totalRefundAmount": { "currencyAmount": 29.06, "currencyUnit": "USD" }, "returnLineGroups": [], "returnOrderLines": [ { "returnOrderLineNumber": 1, "salesOrderLineNumber": 1, "returnReason": "OTHER", "returnDescription": "Seller Issued Refund", "purchaseOrderId": "108913038979891", "purchaseOrderLineNumber": 1, "isReturnForException": false, "item": { "condition": "New", "productName": "Power Rangers: Dino Fury T-Rex Champion Zord Toy Action Figure for Boys and Girls Ages 4 5 6 7 8 and Up", "itemWeight": { "unitOfMeasure": "POUND", "measurementValue": 5 } }, "charges": [ { "chargeCategory": "PRODUCT", "chargeName": "ItemPrice", "chargePerUnit": { "currencyAmount": 29.99, "currencyUnit": "USD" }, "isDiscount": false, "isBillable": true, "tax": [ { "taxName": "Tax1", "excessTax": { "currencyAmount": 0, "currencyUnit": "USD" }, "taxPerUnit": { "currencyAmount": 3.07, "currencyUnit": "USD" } } ], "references": [ { "name": "fulfillmentOrderNo", "value": "108913038979891" }, { "name": "id", "value": "DUMMY_db9a5bb8-7f5c-43a8-b7b8-baa590cc1d33_PRODUCT_8c2803d1-6e8f-496a-927a-4d68a7aac036" }, { "name": "fulfillerLineId", "value": "1" } ] }, { "chargeCategory": "PRODUCT", "chargeName": "Product", "chargePerUnit": { "currencyAmount": -3, "currencyUnit": "USD" }, "isDiscount": true, "isBillable": true, "tax": [ { "taxName": "Product", "excessTax": { "currencyAmount": 0, "currencyUnit": "USD" }, "taxPerUnit": { "currencyAmount": -1, "currencyUnit": "USD" } } ], "excessCharge": { "currencyAmount": 0, "currencyUnit": "USD" }, "references": [ { "name": "fulfillmentOrderNo", "value": "108913038979891" }, { "name": "isDiscount", "value": "true" }, { "name": "id", "value": "001dda93-7d07-4a13-abc9-a3043d28a394" }, { "name": "fulfillerLineId", "value": "1" } ] } ], "unitPrice": { "currencyAmount": 29.99, "currencyUnit": "USD" }, "itemReturnSettings": [], "chargeTotals": [ { "name": "lineUnitPrice", "value": { "currencyAmount": 29.99, "currencyUnit": "USD" } }, { "name": "lineProductTaxes", "value": { "currencyAmount": 3.07, "currencyUnit": "USD" } }, { "name": "lineTotalTaxes", "value": { "currencyAmount": 3.32, "currencyUnit": "USD" } }, { "name": "lineMiscCharges", "value": { "currencyAmount": -3, "currencyUnit": "USD" } }, { "name": "lineSubTotal", "value": { "currencyAmount": 26.99, "currencyUnit": "USD" } }, { "name": "lineTotal", "value": { "currencyAmount": 29.06, "currencyUnit": "USD" } }, { "name": "lineDutyCharges", "value": { "currencyAmount": 1.25, "currencyUnit": "USD" } }, { "name": "lineTaxesAndOtherFees", "value": { "currencyAmount": 3.32, "currencyUnit": "USD" } } ], "cancellableQty": 0, "quantity": { "unitOfMeasure": "EACH", "measurementValue": 1 }, "returnExpectedFlag": false, "isFastReplacement": false, "isKeepIt": false, "lastItem": false, "refundedQty": 1, "rechargeableQty": 0, "refundCoveredBy": "InstantRefund", "returnTrackingDetail": [ { "sequenceNo": 1, "eventTag": "REFUND_ISSUED", "eventDescription": "Refund initiated for MARKET_PLACE", "eventTime": "2024-08-22T11:27:56.829Z", "references": [ { "name": "ReturnDate", "value": "2024-08-22T11:11:41.821Z" }, { "name": "SLA for Receiving Items", "value": "7 Days" } ] }, { "sequenceNo": 0, "eventTag": "RETURN_INITIATED", "eventDescription": "Return created for MARKET_PLACE", "eventTime": "2024-08-22T11:11:41.823Z", "references": [ { "name": "ReturnDate", "value": "2024-08-22T11:11:41.823Z" } ] } ], "status": "COMPLETED", "statusTime": "2024-08-22T11:27:56.000Z", "currentDeliveryStatus": "NOT_SHIPPED", "currentRefundStatus": "REFUND_COMPLETED", "currentTrackingStatuses": [ { "status": "COMPLETED", "statusTime": "2024-08-22T11:27:56.000Z", "currentRefundStatus": "REFUND_COMPLETED", "quantity": { "unitOfMeasure": "EACH", "measurementValue": 1 } } ], "refundChannels": [ { "refundChannelName": "InstantRefund", "quantity": { "measurementValue": 1 } } ] } ], "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.