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:

  1. Item setup: Create or register products (SKUs) with Walmart using the Item Management API.
  2. Inventory management: Keep SKU quantities accurate using the Inventory API.
  3. Order management: Retrieve, confirm, and track orders, shipments, and cancellations through the Orders API.
  4. Pricing: Adjust item prices through Pricing APIs.
  5. 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.

ScenarioView (GET endpoints)Action (POST endpoints)
Retrieve a list of return ordersGET /v3/returns
Retrieves all return orders, optionally filtered by status or date.
Not applicable (view only).
Retrieve details for a return orderGET /v3/returns/{returnOrderId}
Returns detailed information about a single return order.
Not applicable (view only).
Approve or reject returnsGET /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 refundsGET /v3/returns/{returnOrderId}POST /v3/returns/{returnOrderId}/items/{returnOrderItemId}/refund
Issue a full or partial refund for the item.
Provide shipping labelsGET /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:

Market availability

The Walmart Returns API is available for sellers listing on Walmart marketplaces in Mexico and the U.S.

Commonly used terms

TermDescription
Return orderAn order that's created when a customer initiates a return on an item purchased.
Return Order IDA unique identifier for each return order.
Return Order Item IDAn identifier for each line item within a return order.
RefundThe amount reimbursed to the customer after a return is approved.
Return reason codeThe reason provided by the customer for returning an item (such as a damaged or wrong item).

Next steps

See also