Returns API overview
Use the Walmart Marketplace Returns API to manage customer return orders and issue refunds for items sold on Walmart.com or Walmart Marketplace Mexico. As a Walmart seller or approved Solution Provider, you can:
- Retrieve return orders to track items that have been returned or are in the process of being returned.
- Approve or reject return requests based on your return policy or the condition of returned items.
- Issue full or partial refunds based on approved returns.
- Provide shipping labels for returns, if applicable.
How it works
Overall seller journey
In a common user journey, a seller or approved Solution Provider might complete the following Walmart flow:
- Item setup: Create or register products (SKUs) with Walmart using the Item Management API.
- Inventory management: Keep SKU quantities accurate using the Inventory API.
- Order management: Retrieve, confirm, and track orders, shipments, and cancellations through the Orders API.
- Pricing: Adjust item prices through Pricing APIs.
- Returns: Manage return orders and issue refunds using the Returns API.
Returns flow
Within returns management, a typical flow is to view your current return orders and process refunds as needed. The following is an example of how each set of GET endpoints corresponds to relevant POST endpoints.
Scenario | View (GET endpoints) | Action (POST endpoints) |
---|---|---|
Retrieve a list of return orders | GET /v3/returns Retrieves all return orders, optionally filtered by status or date. | Not applicable (view only). |
Retrieve details for a return order | GET /v3/returns/{returnOrderId} Returns detailed information about a single return order. | Not applicable (view only). |
Approve or reject returns | GET /v3/returns/{returnOrderId} | POST /v3/returns/approve POST /v3/returns/reject Approve or reject the return request for specific items or the full order. |
Issue refunds | GET /v3/returns/{returnOrderId} | POST /v3/returns/{returnOrderId}/items/{returnOrderItemId}/refund Issue a full or partial refund for the item. |
Provide shipping labels | GET /v3/returns/{returnOrderId} | POST /v3/returns/{returnOrderId}/items/{returnOrderItemId}/shippinglabel Generate or send a shipping label. |
Reference guide
This guide explains how to integrate the Returns API with practical examples and step-by-step instructions.
For full technical details, including endpoints, parameters, and brief descriptions, refer to the
Walmart Returns API reference guide.
Prerequisites
Complete the following before integrating the Returns API:
- Complete the steps in the Getting started guide:
- If you are a seller, refer to the Getting started guide for sellers.
- If you are an approved Solution Providers, refer to the Getting started guide for solution providers.
- OAuth 2.0 authentication: Required for all Walmart Marketplace APIs. Obtain your credentials and access token before making requests. See OAuth 2.0 authorization.
- Item setup: Ensure your SKUs are created and registered with Walmart before handling returns and refunds.
Market availability
The Walmart Returns API is available for sellers listing on Walmart marketplaces in Mexico and the U.S.
Commonly used terms
Term | Description |
---|---|
Return order | An order that's created when a customer initiates a return on an item purchased. |
Return Order ID | A unique identifier for each return order. |
Return Order Item ID | An identifier for each line item within a return order. |
Refund | The amount reimbursed to the customer after a return is approved. |
Return reason code | The reason provided by the customer for returning an item (such as a damaged or wrong item). |
Next steps
- Download schemas to view request and response formats.
See also
- How to manage item pricing so that refunds reflect the correct price.
- Add event notifications to stay updated on changes in return statuses and other order events.
Updated 15 days ago