Returns

get https://marketplace.walmartapis.com/v3/returns

Retrieves the details of return orders for the specified filter criteria.

Query Params

returnOrderId

string

Return order identifier of the return order object as part of array. This is the same as RMA number.

customerOrderId

string

A unique ID associated with the sales order for specified customer

status

string

Status may be specified to query the returns with specific status.Valid statuses are: INITIATED, DELIVERED, COMPLETED

replacementInfo

string

Provides additional attributes - replacementCustomerOrderID, returnType, rechargeReason, returnCancellationReason - related to Replacement return order, in response, if available. Allowed values are true or false.

returnType

string

Specifies if the return order is a replacement return or a regular (refund) return. Possible values are PREORDER, REPLACEMENT or REFUND.

returnCreationStartDate

date-time

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'

returnCreationEndDate

date-time

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'

returnLastModifiedStartDate

date-time

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

returnLastModifiedEndDate

date-time

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

limit

string

Defaults to 10

The number of orders to be returned. Cannot be larger than 200

Headers

WM_SEC.ACCESS_TOKEN

string

required

The access token retrieved in the Token API call

WM_CONSUMER.CHANNEL.TYPE

string

A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding

WM_QOS.CORRELATION_ID

string

required

A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID

WM_SVC.NAME

string

required

Walmart Service Name

Response

Response body

object

meta

object

required

totalCount

int64

required

limit

int64

required

nextCursor

string

required

returnOrders

array of objects

required

List of returns for the seller.

returnOrders*

object

returnOrderId

string

Return order identifier of the return order. This is the same as RMA number.

customerEmailId

string

Customer email address

returnType

string

Specifies if the return order is a replacement return or a regular (refund) return. Possible values are PREORDER, REPLACEMENT or REFUND.

replacementCustomerOrderId

string

customer order ID of the original return order on which the replacement is created.

customerName

object

Customer information

customerOrderId

string

A unique ID associated with the sales order for specified customer

returnOrderDate

date-time

Date format for return order date

returnByDate

date-time

Date format for return by order date

refundMode

string

Determines when the refund was/will be issued to the customer

totalRefundAmount

object

Price of One unit of item, in this order line

returnLineGroups

array of objects

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

returnLineGroups

object

groupNo

int64

Sequence of group numbers where each returnLineGroups will represent one or more return lines

returnLines

array of objects

Array of return lines

returnLines

object

returnOrderLineNumber

int64

Identifier of the return label

labels

array of objects

Array of labels

labels

object

labelImageURL

string

Url to get the return label

carrierInfoList

array of objects

Carrier information for the return

carrierInfoList

object

carrierId

string

ID of the carrier used for the return

carrierName

string

Name of the carrier used

serviceType

string

the type of service used

trackingNo

string

Tracking number of the order

returnExpectedFlag

boolean

Is customer required to send this item back to return center

returnOrderLines

array of objects

A list of order lines in the return order

returnOrderLines

object

returnOrderLineNumber

int64

The returns order line number for that return

salesOrderLineNumber

int64

The sales order line number for the return created

sellerOrderId

string

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

string

Gives the reason that was selected during the return creation. Reason codes are: ARRIVED_LATE, BOUGHT_ANOTHER_SIZE_OR_COLOR, BOUGHT_SOMEWHERE_ELSE, COLOR_NOT_EXPECTED, DAMAGED, DEFECTIVE, DEVICE/PART(S)_DO_NOT_WORK, DID_NOT_LIKE_FABRIC, DIFFICULT_TO_SETUP/NOT_COMPATIBLE, DUPLICATE_ITEM, INCORRECT_ITEM, ITEM_MISSING, LOST_AFTER_DELIVERY, LOST_IN_TRANSIT, LOWER_PRICE, NOT_AS_DESCRIBED, NO_LONGER_WANTED, OTHER, OUT_OF_STOCK, PACKAGING_OR_ITEMBOX_IS_DAMAGED, RETURN_TO_SENDER, SHIPPING_BOX_DAMAGED, TRIED_TO_CANCEL and WRONG_SIZE/POOR_FIT

returnDescription

string

Gives the returnDescription for the return created. It would be empty if returnDescriptin is 'Fraud'.

purchaseOrderId

string

The purchase order ID for the return created

purchaseOrderLineNumber

int64

The purchase order line number for the return created

exceptionItemType

string

isReturnForException

boolean

rechargeReason

string

reason for recharging the customer for replacement

returnCancellationReason

string

reason for cancelling the return

item

object

Details of the item to be returned

charges

array of objects

Information relating to the charge for the orderLine

charges

object

chargeCategory

string

The category type. (e.g., 'PRODUCT' or 'FEE')

chargeName

string

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

object

Price of One unit of item, in this order line

isDiscount

boolean

Is this charge a discount, which then needs to be subtracted from the refund

isBillable

boolean

Should this charge be included in the refund computation

tax

array of objects

Taxes for each charge

tax

object

taxName

string

Name of the tax

excessTax

object

Amount of excess tax in the order line

taxPerUnit

object

Price of One unit of item, in this order line

excessCharge

object

Price of One unit of item, in this order line

references

array of objects

Used only for OG

references

object

name

string

required

value

string

required

unitPrice

object

Price of One unit of item, in this order line

itemReturnSettings

array of objects

Contains name value pairs of calculated charges for the line. Eg: if order line has 3 Qty, this will have a shipping charge = 3 * shipping charge per unit (This is present in the line level charges).

itemReturnSettings

object

name

string

required

value

string

required

chargeTotals

array of objects

Contains name value pairs of calculated charges for the line. Eg: if order line has 3 Qty, this will have a shipping charge = 3 * shipping charge per unit (This is present in the line level charges).

chargeTotals

object

name

string

required

Charge Names: lineUnitPrice, lineProductTaxes, lineTotalTaxes, lineRestockingFee, lineShippingFee, lineSubTotal, lineTotal.

value

object

required

Price of One unit of item, in this order line

cancellableQty

int64

How much quantity of this order line can be cancelled

quantity

object

Total quantity returned in this return line

returnExpectedFlag

boolean

Is customer required to send this item back to return center.

isFastReplacement

boolean

Applicable only for 1P.

isKeepIt

boolean

Is customer allowed to keep the product and not required to send it back to return center. This flag is determined by making a call to fraud system.

lastItem

boolean

This return is the last item on the sales order line and all other sales order line items are already returned. Helps in last penny calculations.

refundedQty

double

The quantity for which customer was refunded

rechargeableQty

double

The quantity for which customer can be charged again for

refundChannel

string

Determines the mode of refund initiation. Valid values are: WALMART_SETTLED_REFUND, SELLER_AUTO_REFUND, SELLER_MANUAL_REFUND, SELLER_SYSTEM_REFUND, and WALMART_TRIGGERED_REFUND.

returnTrackingDetail

array of objects

Informational blocks added as the return order completes its journey from return creation to received and refunded.

returnTrackingDetail

object

sequenceNo

int64

The stage the return is in. (e.g., '1' is an initiated return)

eventTag

string

The last completed return event. (e.g., 'RETURN_IN_TRANSIT')

eventDescription

string

Description of current return status event. (e.g., 'A MARKET_PLACE Return in Transit')

eventTime

date-time

Timestamp of listed event

references

array of objects

Used only for 1P

references

object

name

string

required

value

string

required

status

string

Current status of return. (e.g., 'INITIATED')

statusTime

date-time

Timestamp of listed status change

currentDeliveryStatus

string

Determines the current carrier tracking status of the return.

currentRefundStatus

string

Determines the current refund status of the return.

currentTrackingStatuses

array of objects

Array of current tracking status of each quantity

currentTrackingStatuses

object

status

string

Current status of return. (e.g., 'INITIATED')

statusTime

date-time

Timestamp of listed status change

currentRefundStatus

string

Determines the current refund status of the return.

quantity

object

Total quantity returned in this return line

refundChannels

array of objects

Array of refund channel of each quantity

refundChannels

object

refundChannelName

string

Valid values are: ONLINE, IN_STORE, and CUSTOMER_CARE

quantity

object

Total quantity returned in this return line

returnChannel

object

The channel via order return got initiated

Language

URL


xxxxxxxxxx
1
curl --request GET \
2
     --url 'https://marketplace.walmartapis.com/v3/returns?limit=10' \
3
     --header 'accept: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Successful Operation