Buyers can now Initiate Returns from Walmart.com for Marketplace seller items (Except for HAZMAT, OTHER or FREIGHT items). For item in the exception categories: HAZMAT or OTHER, sellers need to generate the return shipping label, and upload the label. For detailed instructions, and to download the Returns API JSON schema, see Returns guide.
openapi: 3.0.1
info:
title: Walmart Returns Management
description: 'Buyers can now Initiate Returns from Walmart.com for Marketplace seller items (Except for HAZMAT, OTHER or FREIGHT items). For item in the exception categories: HAZMAT or OTHER, sellers need to generate the return shipping label, and upload the label. For detailed instructions, and to download the Returns API JSON schema, see Returns guide.'
servers:
- url: https://marketplace.walmartapis.com
description: Production URL
- url: https://sandbox.walmartapis.com
description: Sandbox URL
security:
- basicScheme: []
paths:
"/v3/returns/{returnOrderId}/refund":
post:
tags:
- Returns/Refunds
summary: Walmart Issue Refund
description: "This API allows sellers to issue refund against a return order. Multiple return order lines can be refunded in one request.\n\nNote: Sellers can use the Refund Order Lines API for all non-exception category items, including adjustments that seller needs to determine a partial refund amount. Especially for exception category items: HAZMAT, OTHER and FREIGHT that are not eligible for the Marketplace Returns Program. "
externalDocs:
description: View Guide
url: "/doc/us/mp/us-mp-returns/#4438"
operationId: issueRefund
parameters:
- name: returnOrderId
in: path
description: The return order ID
required: true
schema:
type: string
- in: header
name: WM_SEC.ACCESS_TOKEN
description: The access token retrieved in the Token API call
required: true
schema:
type: string
example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
- in: header
name: WM_CONSUMER.CHANNEL.TYPE
description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding
required: false
schema:
type: string
- in: header
name: WM_QOS.CORRELATION_ID
description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
required: true
schema:
type: string
example: b3261d2d-028a-4ef7-8602-633c23200af6
- in: header
name: WM_SVC.NAME
description: Walmart Service Name
required: true
schema:
type: string
example: Walmart Service Name
requestBody:
description: File fields
content:
application/json:
schema:
required:
- customerOrderId
- refundLines
type: object
properties:
customerOrderId:
type: string
description: A unique ID associated with the sales order for specified customer
refundLines:
type: array
description: Array of refund lines.
items:
required:
- returnOrderLineNumber
type: object
properties:
returnOrderLineNumber:
type: integer
description: A line number associated with each individual line in the return order. If return order has only one return order line and it is not provided in the request, the only available return order line is auto-selected. If return order has multiple return order lines, the required return order line must be provided in the request. If not provided in the request, it will result in data-error.
format: int64
quantity:
required:
- measurementValue
- unitOfMeasure
type: object
properties:
unitOfMeasure:
type: string
description: The unit of measure in the item's weight (e.g., 'EACH' or 'EA')
measurementValue:
type: number
description: The quantity of the unit of measure for the item
format: double
description: Total quantity returned in this return line
description: Array of refund lines.
example:
customerOrderId: '1535274411287'
refundLines:
- returnOrderLineNumber: 1
quantity:
unitOfMeasure: EA
measurementValue: 2
required: true
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
returnOrderId:
type: string
description: The return order id
customerOrderId:
type: string
description: A unique ID associated with the sales order for specified customer
refundLines:
type: array
description: Array of refund lines
items:
required:
- returnOrderLineNumber
type: object
properties:
returnOrderLineNumber:
type: integer
description: A line number associated with each individual line in the return order. If return order has only one return order line and it is not provided in the request, the only available return order line is auto-selected. If return order has multiple return order lines, the required return order line must be provided in the request. If not provided in the request, it will result in data-error.
format: int64
quantity:
required:
- measurementValue
- unitOfMeasure
type: object
properties:
unitOfMeasure:
type: string
description: The unit of measure in the item's weight (e.g., 'EACH' or 'EA')
measurementValue:
type: number
description: The quantity of the unit of measure for the item
format: double
description: Total quantity returned in this return line
description: Array of refund lines.
example:
returnOrderId: '106152711271982880'
customerOrderId: '1535274411287'
refundLines:
- returnOrderLineNumber: 1
quantity:
unitOfMeasure: EA
measurementValue: 2
"/v3/feeds":
post:
tags:
- Returns/Refunds
summary: Walmart Return Item Overrides
description: |-
Sellers can specify global settings for returns in Seller Center, and they can override individual item level settings using this API.
Empty values for the settings will remove the existing overriden values and revert them to global settings.
For more details, see the announcement for [Bulk Return Rules](https://sellerhelp.walmart.com/s/guide?article=000008197).
operationId: bulkItemOverrideFeed
parameters:
- name: feedType
in: query
description: Feed Type
required: true
schema:
type: string
default: RETURNS_OVERRIDES
- in: header
name: WM_SEC.ACCESS_TOKEN
description: The access token retrieved in the Token API call
required: true
schema:
type: string
example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
- in: header
name: WM_CONSUMER.CHANNEL.TYPE
description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding
required: false
schema:
type: string
- in: header
name: WM_QOS.CORRELATION_ID
description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
required: true
schema:
type: string
example: b3261d2d-028a-4ef7-8602-633c23200af6
- in: header
name: WM_SVC.NAME
description: Walmart Service Name
required: true
schema:
type: string
example: Walmart Service Name
requestBody:
content:
multipart/form-data:
schema:
required:
- file
type: object
properties:
file:
type: string
description: Feed file to upload
format: binary
examples:
sample1:
value:
header:
feedDate: '2018-08-31T20:59:14.000Z'
overrideFeed:
- sku: ABC001
overrides:
returnCenterAlias: CAL1
sample2:
value:
header:
feedDate: '2018-08-31T20:59:14.000Z'
overrideFeed:
- sku: ABC002
overrides:
isKeepIt: 'Yes'
sample3:
value:
header:
feedDate: '2018-08-31T20:59:14.000Z'
overrideFeed:
- sku: ABC003
overrides:
isReturnRestricted: 'No'
sample4:
value:
header:
feedDate: '2018-08-31T20:59:14.000Z'
overrideFeed:
- sku: ABC004
overrides:
isKeepIt: ''
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
type: object
properties:
feedId:
type: string
description: A unique ID, returned from the Bulk Upload API, used for tracking the Feed File.
example:
feedId: C0771C26FF1A4282A73C6F3EB659D9BF@ATgBAQA
"/v3/returns":
get:
tags:
- Returns/Refunds
summary: Walmart Returns
description: Retrieves the details of return orders for the specified filter criteria.
externalDocs:
description: View Guide
url: "/doc/us/mp/us-mp-returns/"
operationId: getReturns
parameters:
- name: returnOrderId
in: query
description: Return order identifier of the return order object as part of array. This is the same as RMA number.
required: false
schema:
type: string
- name: customerOrderId
in: query
description: A unique ID associated with the sales order for specified customer
required: false
schema:
type: string
- name: status
in: query
description: 'Status may be specified to query the returns with specific status.Valid statuses are: INITIATED, DELIVERED, COMPLETED'
required: false
schema:
type: string
- name: replacementInfo
in: query
description: Provides additional attributes - replacementCustomerOrderID, returnType, rechargeReason, returnCancellationReason - related to Replacement return order, in response, if available. Allowed values are true or false.
required: false
schema:
type: string
- name: returnType
in: query
description: Specifies if the return order is a replacement return or a regular (refund) return. Possible values are REPLACEMENT or REFUND.
required: false
schema:
type: string
- name: returnCreationStartDate
in: query
description: 'Start Date for querying all return orders that were created after that date. Use one of the following formats, based on UTC, ISO 8601. Date example: ''2013-08-16'' Timestamp example: ''2013-08-16T10:30:15Z'''
required: false
schema:
type: string
format: date-time
- name: returnCreationEndDate
in: query
description: 'Limits the query to the return orders that were created before this returnCreationEndDate. Use one of the following formats, based on ISO 8601, are allowed: UTC date or timestamp. Examples: ''2016-08-16T10:30:30.155Z'' or ''2016-08-16'''
required: false
schema:
type: string
format: date-time
- name: returnLastModifiedStartDate
in: query
description: 'Start Date for querying all return orders that were modified after that date. Use one of the following formats, based on UTC, ISO 8601. Date example: ''2013-08-16'' Timestamp example: ''2013-08-16T10:30:15Z''.In case of dates with timezone, use format ''2020-04-17T10:42:41.000+0000'' and follow encode ''+'' with %20'
required: false
schema:
type: string
format: date-time
- name: returnLastModifiedEndDate
in: query
description: 'Limits the query to the return orders that were modified before this date. Use one of the following formats, based on UTC, ISO 8601. Date example: ''2013-08-16'' Timestamp example: ''2013-08-18T10:30:15Z''.In case of dates with timezone, use format ''2020-04-18T10:42:41.000+0000'' and follow encode ''+'' with %20'
required: false
schema:
type: string
format: date-time
- name: limit
in: query
description: The number of orders to be returned. Cannot be larger than 200
required: false
schema:
type: string
default: '10'
- in: header
name: WM_SEC.ACCESS_TOKEN
description: The access token retrieved in the Token API call
required: true
schema:
type: string
example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
- in: header
name: WM_CONSUMER.CHANNEL.TYPE
description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding
required: false
schema:
type: string
- in: header
name: WM_QOS.CORRELATION_ID
description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
required: true
schema:
type: string
example: b3261d2d-028a-4ef7-8602-633c23200af6
- in: header
name: WM_SVC.NAME
description: Walmart Service Name
required: true
schema:
type: string
example: Walmart Service Name
responses:
'200':
description: Successful Operation
content:
application/json:
schema:
required:
- meta
- returnOrders
type: object
properties:
meta:
required:
- limit
- nextCursor
- totalCount
type: object
properties:
totalCount:
type: integer
format: int64
limit:
type: integer
format: int64
nextCursor:
type: string
returnOrders:
type: array
description: List of returns for the seller.
items:
type: object
properties:
returnOrderId:
type: string
description: Return order identifier of the return order. This is the same as RMA number.
customerEmailId:
type: string
description: Customer email address
returnType:
type: string
description: Specifies if the return order is a replacement return or a regular (refund) return. Possible values are REPLACEMENT or REFUND.
replacementCustomerOrderId:
type: string
description: customer order ID of the original return order on which the replacement is created.
customerName:
type: object
properties:
firstName:
type: string
description: Customer first name
lastName:
type: string
description: Customer last name
description: Customer information
customerOrderId:
type: string
description: A unique ID associated with the sales order for specified customer
returnOrderDate:
type: string
description: Date format for return order date
format: date-time
returnByDate:
type: string
description: Date format for return by order date
format: date-time
refundMode:
type: string
description: Determines when the refund was/will be issued to the customer
totalRefundAmount:
required:
- currencyAmount
- currencyUnit
type: object
properties:
currencyAmount:
type: number
description: Amount to be refunded. It can be upto two decimal points.
format: double
currencyUnit:
type: string
description: Currency information
description: Price of One unit of item, in this order line
returnLineGroups:
type: array
description: These groups are created per label or type of carrier service required. (e.g., If order has some lines that can be clubbed and mailed together as a smart post then they belong to one return group. If a line is bulky and needs a different type of carrier service, then that line will be part of different group. Customer gets multiple labels depending on how many groups are created for the entire order.)
items:
type: object
properties:
groupNo:
type: integer
description: Sequence of group numbers where each returnLineGroups will represent one or more return lines
format: int64
returnLines:
type: array
description: Array of return lines
items:
type: object
properties:
returnOrderLineNumber:
type: integer
description: Identifier of the return label
format: int64
description: Array of return lines
labels:
type: array
description: Array of labels
items:
type: object
properties:
labelImageURL:
type: string
description: Url to get the return label
carrierInfoList:
type: array
description: Carrier information for the return
items:
type: object
properties:
carrierId:
type: string
description: ID of the carrier used for the return
carrierName:
type: string
description: Name of the carrier used
serviceType:
type: string
description: the type of service used
trackingNo:
type: string
description: Tracking number of the order
description: Carrier information for the return
description: Array of labels
returnExpectedFlag:
type: boolean
description: Is customer required to send this item back to return center
description: These groups are created per label or type of carrier service required. (e.g., If order has some lines that can be clubbed and mailed together as a smart post then they belong to one return group. If a line is bulky and needs a different type of carrier service, then that line will be part of different group. Customer gets multiple labels depending on how many groups are created for the entire order.)
returnOrderLines:
type: array
description: A list of order lines in the return order
items:
type: object
properties:
returnOrderLineNumber:
type: integer
description: The returns order line number for that return
format: int64
salesOrderLineNumber:
type: integer
description: The sales order line number for the return created
format: int64
sellerOrderId:
type: string
description: A unique ID associated with the sales order for specified Seller; gives Sellers the ability to print their own custom order ID on the return label; limit of 30 characters
returnReason:
type: string
description: 'Gives the reason that was selected during the return creation. Reason codes are: ARRIVED_LATE, AUTO_RETURN, BOUGHT_ANOTHER_SIZE_OR_COLOR, BOUGHT_SOMEWHERE_ELSE, DAMAGED, DEFECTIVE, DUPLICATE_ITEM, INADEQUATE_QUALITY, INCORRECT_ITEM, LOST_AFTER_DELIVERY, LOST_IN_TRANSIT, LOWER_PRICE, MISSING_PARTS, NOT_AS_DESCRIBED, NO_LONGER_WANTED, RETURN_TO_SENDER, SHIPPING_BOX_DAMAGED, TRIED_TO_CANCEL and WRONG_SIZE/POOR_FIT'
purchaseOrderId:
type: string
description: The purchase order ID for the return created
purchaseOrderLineNumber:
type: integer
description: The purchase order line number for the return created
format: int64
exceptionItemType:
type: string
isReturnForException:
type: boolean
rechargeReason:
type: string
description: reason for recharging the customer for replacement
returnCancellationReason:
type: string
description: reason for cancelling the return
item:
type: object
properties:
sku:
type: string
description: An arbitrary alphanumeric unique ID, specified by the seller, which identifies each item.
condition:
type: string
description: Information about the condition of the product.
productName:
type: string
description: 'The name of the product associated with the line item. Example: ''Kenmore CF1'' or ''2086883 Canister Secondary Filter Generic 2 Pack'''
itemWeight:
required:
- measurementValue
- unitOfMeasure
type: object
properties:
unitOfMeasure:
type: string
description: The unit of measure in the item's weight (e.g., 'EACH' or 'EA')
measurementValue:
type: number
description: The quantity of the unit of measure for the item
format: double
description: Total quantity returned in this return line
description: Details of the item to be returned
charges:
type: array
description: Information relating to the charge for the orderLine
items:
type: object
properties:
chargeCategory:
type: string
description: The category type. (e.g., 'PRODUCT' or 'FEE')
chargeName:
type: string
description: If chargeType is PRODUCT, chargeName is ItemPrice. If chargeType is PRODUCT and includes a chargeName as SubscriptionDiscount, these are subscription orders with a discount. If chargeType is SHIPPING, chargeName is Shipping
chargePerUnit:
required:
- currencyAmount
- currencyUnit
type: object
properties:
currencyAmount:
type: number
description: Amount to be refunded. It can be upto two decimal points.
format: double
currencyUnit:
type: string
description: Currency information
description: Price of One unit of item, in this order line
isDiscount:
type: boolean
description: Is this charge a discount, which then needs to be subtracted from the refund
isBillable:
type: boolean
description: 'Should this charge be included in the refund computation
'
tax:
type: array
description: Taxes for each charge
items:
type: object
properties:
taxName:
type: string
description: Name of the tax
excessTax:
required:
- currencyAmount
- currencyUnit
type: object
properties:
currencyAmount:
type: number
description: Amount to be refunded. It can be upto two decimal points.
format: double
currencyUnit:
type: string
description: Currency information
description: Amount of excess tax in the order line
taxPerUnit:
required:
- currencyAmount
- currencyUnit
type: object
properties:
currencyAmount:
type: number
description: Amount to be refunded. It can be upto two decimal points.
format: double
currencyUnit:
type: string
description: Currency information
description: Price of One unit of item, in this order line
description: Taxes for each charge
excessCharge:
required:
- currencyAmount
- currencyUnit
type: object
properties:
# --- truncated at 32 KB (139 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/walmart/refs/heads/main/openapi/walmart-marketplace-returns-openapi-original.yml