Create return for customer order for WFS item

Call this endpoint to create a customer return order in Walmart Multichannel Solutions (MCS). You can use this API to generate a return for an order that is WFS MCS fulfilled. Walmart generates a return record, routes the package to the correct facility, and tracks receiving.

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

Endpoint

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

Sample request

This sample request creates a customer return in MCS.

curl --request POST \ --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>' \ --data '{ "header": { "headerAttributes": { "buId": "0", "martId": "202" } }, "payload": { "sellerReturnOrderId": "98966341-2944-49c5-bba3-ee167f667e04", // unique per return; good for idempotency "sellerOrderId": "SO-123456", // your original order id (no spaces) "orderItems": [ { "returnReason": "DAMAGED", // use a supported reason code, not free text "itemDetail": { "sku": "SKU-ABC-001" // your SKU that was fulfilled by MCS }, "qty": { "unitOfMeasure": "EA", "measurementValue": 1 } } ] } }'

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>",
} json_data = { "header": { "headerAttributes": { "buId": "0", "martId": "202" } }, "payload": { "sellerReturnOrderId": "98966341-2944-49c5-bba3-ee167f667e04", "sellerOrderId": "SO-123456", "orderItems": [ { "returnReason": "DAMAGED", "itemDetail": { "sku": "SKU-ABC-001" }, "qty": { "unitOfMeasure": "EA", "measurementValue": 1 } } ] }
} response = requests.post(url, headers=headers, json=json_data)
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.
The sellerOrderId and the item sku must match the original MCS fulfilled order.

Sample response

The API returns a successful response after creating a return for the customer order.

{ "status": "OK", "header": { "headerAttributes": { "pageCount": 1, "totalCount": 1, "martId": "202", "buId": "0" } }, "payload": { "sellerReturnOrderId": "98966341-2944-49c5-bba3-ee167f667e02", "returnOrderId": "156275470377404264", "sellerOrderId": "200011888200325", "returnOrderLines": [ { "lineNo": 1, "returnMode": "MAIL", "returnReason": "Changed Mind", "returnReasonDesc": "No Longer Wanted", "itemDetail": { "sku": "00080119078374" }, "qty": { "unitOfMeasure": "EA", "measurementValue": 1 } } ], "returnLineGroups": \[ { "groupNo": 1, "returnOrderGroupLines": [ { "lineNo": 1, "quantity": { "unitOfMeasure": "EA", "measurementValue": 1 } } ], "labelImageURL": "Label Image url ", "carrierInfo": { "carrierName": "FEDEX", "trackingNo": "274958338948", "trackingUrl": "<https://www.fedex.com/apps/fedextrack/"> }, "shipFrom": { "address": { "addressLineOne": "11926 Smalley Ave", "addressType": "RESIDENTIAL", "city": "Grandview", "countryCode": "USA", "postalCode": "64030", "stateOrProvinceCode": "MO" }, "name": { "completeName": "Toni Ichrist", "firstName": "Toni", "lastName": "Ichrist" }, "phone": "1234567908", "email": "[[email protected]](mailto:[email protected])" }, "shipTo": { "address": { "addressLineOne": "130 Velocity Way", "city": "Shepherdsville", "countryCode": "USA", "postalCode": "40165", "stateOrProvinceCode": "KY" }, "name": { "completeName": "First Last", "firstName": "First" }, "phone": "1234567890", "email": "[[email protected]](mailto:[email protected])" } } ] }, "headers": { "headerAttributes": { "buId": "0", "martId": "202" } } }

Result

Walmart creates the MCS return order and responds with a JSON body that includes a Walmart-generated return order identifier returnOrderId, your sellerReturnOrderId, the accepted line items (SKU, quantity, reason), and an initial status (CREATED). Store both IDs for reconciliation and future lookups.

Updated 4 days ago