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 20 days ago