Use the Order management API to refund the items on a captured order.
When your customers return the items they bought and you need to refund that order, use this API call to credit the amount back to your customers.
The following diagram depicts how this API call works:
Sequence diagram of the API call to refund an order.
If you want to learn how to correctly allocate refunds when you deliver in multiple shipments, see the Refund allocation section.
To refund the amount of an order, send a POST request to the {apiUrl}/ordermanagement/v1/orders/{order_id}/refunds endpoint.
Include the following in your request:
Header
Body
{
"refunded_amount": 100000000",
"reference": "9dfcd4b6-9428-4835-ad93-3720ea808608",
"description": "Description of the refund shown to the customer",
"order_lines": [
{
"image_url": "https://yourstore.example/product/headphones.png",
"merchant_data": "Some metadata",
"name": "string",
"product_identifiers": {
Sample of a request to refund an order.
If the request is successful, you'll receive a 201 Created
response, including refund_id
and location
as HTTP response headers.
If your request contains errors, you'll receive an error response. Make sure the order is already captured and the order_id
is correct.
You can use the correlation_id
and the order_id
values to troubleshoot the call in the Merchant portal logs section.
{
"error_code": "REFUND_NOT_ALLOWED",
"error_messages": [
"Over refund is not allowed. Refund not possible."
],
"correlation_id": "7863c755-eb1b-4b24-a884-06c2368389d7"
}
Sample of an error response to refund an order.
Ready to send this request? See the API reference of this call.