Call this endpoint to retrieve a paginated list of Walmart Multichannel Solutions (MCS) customer return order details. You can retrieve details including:

Return status updates (Created, canceled, initiated, received, completed)
Return Merchandize Authorization (RMA) ID, originating order ID, original order date
Expected item and actual item
Expected weight and actual weight
Expected item conditions and actual condition
Grading codes (sellable, unsellable, unexpected item, disposed or, or hazmat)

This page describes an example using only the required parameters and inputs to get the return status for a customer order. For a full list of customization options and additional capabilities, refer to the Marketplace WFS Multichannel solutions API Reference.

Endpoint

GET https://marketplace.walmartapis.com/v3/fulfillment/return-orders

Sample request

This sample request retrieves the customer return order status.

curl --request GET \ --url 'https://marketplace.walmartapis.com/v3/fulfillment/return-orders' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'WM_SEC.ACCESS_TOKEN: <your_oauth_access_token>' \ --header 'WM_SVC.NAME: Walmart Marketplace' \ --header 'WM_QOS.CORRELATION_ID: <uuid-for-this-call>'

import requests url = "https://marketplace.walmartapis.com/v3/fulfillment/return-orders" headers = { "Accept": "application/json", "Content-Type": "application/json", "WM_SEC.ACCESS_TOKEN": "<your_oauth_access_token>", "WM_SVC.NAME": "Walmart Marketplace", "WM_QOS.CORRELATION_ID": "<uuid-for-this-call>",
} response = requests.get(url, headers=headers)
print(response.status_code)
print(response.text)

Modify your code

Use a unique WM_QOS.CORRELATION_ID for each request.
Replace WM_SEC.ACCESS_TOKEN with your valid access token obtained through authentication.

Sample response

The API returns a successful response once customer return order status information is retrieved.

{ "header": { "headerAttributes": { "martId": "202", "buId": "0", "pageCount": 1, "totalCount": 2271 } }, "payload": [ { "returnOrderId": "330044524157165704", "sellerReturnOrderId": "98966341-2944-49c5-bba3-ee167f667e04", "sellerOrderId": "RAPMOCK1719065835761", "channelName": "MCS", "status": "CREATED", "createdDate": "2024-06-10T20:01:32Z", "lastUpdatedDate": "2024-06-10T20:01:32Z", "returnOrderLines": [ { "lineNo": "1", "returnReason": "DAMAGED", "returnReasonDesc": "Item arrived damaged", "itemDetail": { "sku": "SKU-EXAMPLE-001", "description": "Item 1" }, "qty": { "unitOfMeasure": "EA", "measurementValue": 1 }, "lineQuantityInfo": [ { "status": "MARKETPLACE_RETURN_INITIATED", "statusCode": 1000, "statusDescription": "Marketplace return initiated", "statusQuantity": { "unitOfMeasure": "EA", "measurementValue": 0 } }, { "status": "PENDING_REFUND", "statusCode": 1900, "statusDescription": "Pending refund", "statusQuantity": { "unitOfMeasure": "EA", "measurementValue": 0 } }, { "status": "EARLY_RETURN_INVOICED", "statusCode": 2000, "statusDescription": "Early return invoiced", "statusQuantity": { "unitOfMeasure": "EA", "measurementValue": 1 } } ], "imageURL": "https://cdn.example.com/image.jpg", "faultCategory": "SELLER", "inspectionComments": "UNSELLABLE", "dispositionCode": "DISPOSE" } ], "returnLineGroups": [ { "groupNo": "1", "returnOrderGroupLines": [ { "lineNo": "1", "qty": { "unitOfMeasure": "EA", "measurementValue": 1 } } ], "labelImageUrl": "https://cdn.example.com/label.png", "carrierInfo": { "carrierName": "FEDEX", "trackingNo": "271113170170", "trackingUrl": "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=271113170170" }, "shipFrom": { "address": { "addressLineOne": "Street address", "city": "City", "countryCode": "US", "postalCode": "12345", "stateOrProvinceCode": "CA" }, "name": { "completeName": "Bill To Name", "firstName": "Bill" }, "phone": "1112223333", "email": "[email protected]" }, "shipTo": { "address": { "addressLineOne": "Street address", "city": "City", "countryCode": "US", "postalCode": "12345", "stateOrProvinceCode": "NV" }, "name": { "completeName": "First Last", "firstName": "First" }, "phone": "8009256278", "email": "[email protected]" } } ], "returnLineDisputes": [ { "disputeCreationTime": "2024-06-10T20:01:32Z", "disputeDescription": "Return received: incorrect item", "disputeReasonCode": "20", "currentDisputeStatus": "APPROVED", "upc": "00784853980671" }, { "disputeCreationTime": "2024-06-10T12:56:33Z", "disputeDescription": "Return received: incorrect item", "disputeReasonCode": "20", "currentDisputeStatus": "MANUAL_REVIEW", "upc": "00784853980671" } ] } ]
}

Result

Returns 200 OK with a paginated list plus a payload array for each return.