Returns API overview

Use the Walmart Marketplace Returns API to manage customer return orders and issue refunds for items sold on Walmart.com. 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.

Return statuses

Each return order line includes a high-level status and a more specific eventTag value in the returnTrackingDetail object. These help you determine where the return is in its lifecycle.

Return status	Event tag	Description
`INITIATED`	`RETURN_INITIATED`	The return was initiated by the customer
`INITIATED`	`RETURN_IN_TRANSIT`	The item is currently in transit back to the return center
`DELIVERED`	`DELIVERED_AT_RETURN_CENTER`	The return was delivered to the return center
`COMPLETED`	`REFUND_INITIATED`	The refund process has started
`COMPLETED`	`REFUND_ISSUED`	The customer has been refunded
`COMPLETED`	`RETURN_CANCELLED`	The return was canceled before completion
`COMPLETED`	`INTRANSIT_AFTER_INVOICE`	The refund was issued before the return item arrived
`COMPLETED`	`DELIVERED_AFTER_INVOICE`	The item was delivered after the refund was already issued

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).

WFS returns

You can retrieve return orders for Walmart Fulfillment Services (WFS) items by using the GET /v3/returns endpoint with the query parameter isWFSEnabled=Y.

Note: WFS returns are view-only. Sellers cannot approve, reject, or issue refunds for WFS return orders.

Next steps

Download schemas to view request and response formats.