Return notifications

Return notifications report key milestones in the return lifecycle: creation, delivery, and invoicing/refund. Walmart sends a JSON payload to your destination URL for each event. Use these events to start or update return workflows, notify customers, and reconcile inventory and refunds.

RETURN_CREATED

This event is triggered when a customer initiates a return for one or more items on an order. The payload includes the Return Merchandise Authorization (RMA) identifier, item and quantity, reason, tracking details, and current refund status. Use returnOrderId as the RMA number in your Order Management System (OMS).

Event metadata

Event Type: RETURN_CREATED
Event Version: V1
Resource Name: RETURNS

Response parameters

Name	Description	Type
source	Metadata about the event	Object
eventType	Event for which the notification is received	String
eventTime	Timestamp of when the event occurred	String
eventId	Unique identifier of the event	String
payload	Event-specific details	Object
partnerId	Seller’s partner ID	String
partnerName	Seller's display name	String
returnOrders	List of return orders included in this event. Each object describes one returned line	List
purchaseOrderId	A unique purchase order identifier associated with the return	String
productName	Product name for the returned item	String
returnOrderId	Return order identifier. Same value used as the RMA number	String
returnInitiatedDate	Date the return was initiated. Format follows the emitting system; sample uses Mar 28, 2024	String
returnReason	Reason selected during return creation	String
quantity	Quantity being returned (numeric string). Example: 1.	String
trackingUrl	One or more carrier tracking URLs for the return shipment	List
trackingId	One or more carrier tracking numbers for the return shipment	List
refundStatus	Refund status for this return line. Example: Non Refunded	String

Sample payload: RETURN_CREATED

{ "partnerId": "10900015773", "partnerName": "StageTestSeller2 llc" "returnOrders": [ { "purchaseOrderId": "RAPMOCK0000007124873", "productName": "Item 1", "returnOrderId": "100006868600000090", "returnInitiatedDate": "Mar 28, 2024", "returnReason": "Item arrived damaged", "quantity": "1", "trackingUrl": [ "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=100070000851" ], "trackingId": [ "100070000851" ], "refundStatus": "Non Refunded" } ]
}

RETURN_INVOICED

This event is triggered when a return is invoiced and the refund process begins. Use this event to update refunds in your Order Management System, notify customers, and reconcile accounting. Walmart sends the JSON payload to your configured destination URL.

Event metadata

Event Type: RETURN_INVOICED
Event Version: V1
Resource Name: RETURNS

Response parameters

Name	Description	Type
source	Metadata about the event	Object
eventType	Event for which the notification is received	String
eventTime	Timestamp of when the event occurred	String
eventId	Unique identifier of the event	String
payload	Event-specific details	Object
partnerId	Seller’s partner ID	String
partnerName	Seller's display name	String
returnOrders	List of return orders included in this event. Each object describes one returned line	List
purchaseOrderId	A unique purchase order identifier associated with the return	String
productName	Product name for the returned item	String
returnOrderId	Return order identifier. Same value used as the RMA number	String
refundInitiatedDate	Date the return was initiated. Format follows the emitting system; sample uses Mar 28, 2024	String
returnReason	Reason selected during return creation	String
quantity	Quantity being returned (numeric string). Example: 1.	String
trackingUrl	One or more carrier tracking URLs for the return shipment	List
trackingId	One or more carrier tracking numbers for the return shipment	List
refundStatus	Refund status for this return line. Example: Non Refunded	String

Sample payload: RETURN_INVOICED

{ "partnerId": "10900024715", "partnerName": "Rons Widgets Live", "returnOrders": [ { "purchaseOrderId": "RAPMOCK0000007124873", "productName": "Trunk Floor Center Panel for 1961-1964 Chevrolet", "returnOrderId": "100006868600000090", "refundInitiatedDate": "Mar 26, 2024", "returnReason": "Shipping box damaged", "quantity": "1", "trackingUrl": [ "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=100070000851" ], "trackingId": [ "100070000851" ], "refundStatus": "Refunded" } ]
}

RETURN_DELIVERED

This event is triggered when a return shipment is delivered to the seller or designated facility. Use this event to mark the return as received, start inspection, and proceed toward invoicing and refund. Walmart sends the JSON payload to your configured destination URL.

Event metadata

Event Type: RETURN_DELIVERED
Event Version: V1
Resource Name: RETURNS

Response parameters

Name	Description	Type
source	Metadata about the event	Object
eventType	Event for which the notification is received	String
eventTime	Timestamp of when the event occurred	String
eventId	Unique identifier of the event	String
payload	Event-specific details	Object
partnerId	Seller’s partner ID	String
partnerName	Seller's display name	String
returnOrders	List of return orders included in this event. Each object describes one returned line	List
purchaseOrderId	A unique purchase order identifier associated with the return	String
productName	Product name for the returned item	String
returnOrderId	Return order identifier. Same value used as the RMA number	String
returnInitiatedDate	Date the return was initiated. Format follows the emitting system; sample uses Mar 28, 2024	String
returnReason	Reason selected during return creation	String
quantity	Quantity being returned (numeric string). Example: 1.	String
trackingUrl	One or more carrier tracking URLs for the return shipment	List
trackingId	One or more carrier tracking numbers for the return shipment	List
refundStatus	Refund status for this return line. Example: Non Refunded	String

Sample payload: RETURN_DELIVERED

{ "partnerId": "10900015173", "partnerName": "Shoes.com", "returnOrders": [ { "purchaseOrderId": "RAPMOCK0000007124873", "productName": "suanret Ladies Satin long sleeve pjs", "returnOrderId": "100006868600000090", "returnInitiatedDate": "Mar 12, 2024", "returnReason": "Shipping box damaged", "quantity": "1", "trackingUrl": [ "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=100070000851" ], "trackingId": [ "100070000851" ], "refundStatus": "Non Refunded" } ]
}