Issue a refund

Call this endpoint to issue refunds for a given return order. Use this endpoint to process full or partial refunds based on the approved return order data. Once a refund is issued, a summary response is returned with the return order ID, customer order ID, and details about the refunded lines.

Note: This example uses only the required parameters for issuing refunds. For additional details and optional parameters, refer to the Returns API Reference.

Endpoint

POST https://marketplace.walmartapis.com/v3/returns/{returnOrderId}/refund

Refund rules and restrictions

• You can only issue refunds for order lines that have a status of Shipped.
• The amount value in the refund request must be negative.
• The refund amount cannot exceed the original amount charged for that item.
• Partial refunds are supported at the line item level.

Note: Refunds cannot be issued for Walmart Fulfillment Services (WFS) return orders. These are view-only and must be handled by Walmart.

Sample request

This sample demonstrates how to issue refunds using the POST /v3/returns/{returnOrderId}/refund endpoint. Replace {returnOrderId} with the actual return order identifier for which you want to process a refund.

curl -X POST "https://marketplace.walmartapis.com/v3/returns/{returnOrderId}/refund" \ -H "Authorization: Basic <Base64EncodedConsumerKey:ConsumerSecret>" \ -H "WM_SVC.NAME: Walmart Marketplace" \ -H "WM_QOS.CORRELATION_ID: 1234567890" \ -H "Accept: application/json" \ -H "Content-Type: application/json"

import requests returnOrderId = "<ReturnOrderId>" # Replace with your actual return order ID
url = f"https://marketplace.walmartapis.com/v3/returns/{returnOrderId}/refund" headers = { "Authorization": "Basic <Base64EncodedConsumerKey:ConsumerSecret>", "WM_SVC.NAME": "Walmart Marketplace", "WM_QOS.CORRELATION_ID": "1234567890", "Accept": "application/json", "Content-Type": "application/json"
} response = requests.post(url, headers=headers)
print("Status code:", response.status_code)
print("Response JSON:", response.json()) 

Modify your code

1. Replace <Base64EncodedConsumerKey:ConsumerSecret> with your actual Base64-encoded credentials.
2. Replace {returnOrderId} with the actual return order identifier for which you wish to process a refund.

Sample response

{ "returnOrderId": "1000000001", "customerOrderId": "2000000001", "refundLines": [ { "returnOrderLineNumber": 1, "quantity": { "unitOfMeasure": "EA", "measurementValue": 2 } } ]
}

Result

If successful, the API returns an HTTP status of 200 OK with a JSON payload confirming that the refund has been processed. The response includes key details such as the return order ID, customer order ID, and a list of refund lines showing the refunded quantities. This response verifies that the refund request was accepted and provides a record of the refunded items.

Troubleshooting

Use the following table to resolve errors that can occur when issuing a refund.

Note: If you get a HTTP status 500 error, try the request again (often a temporary issue). For HTTP status 400 errors, check and fix your input before retrying.