Skip to main content

Refund order

If an end customer requires money back as compensation or after returning an item. Use this endpoint to refund the entire order, part refund individual items, a specific quantity of items of an order or as an adjustment amount.

Please note

This can only be done on orders with status Activated or PartActivated

Full refund​

You can refund the entire order by simply specifying the amount to refund. This only allows for the full amount left on the order that has been captured. If you are doing a part refund, you will have to provide items in the request that partial refund can be matched against.

POST /manage/orders/{{orderId}}/refund HTTP/1.1
Host: api.uat.walleydev.com // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
"amount": 285.0,
"description": "Refund description",
"actionReference": "test-refundref-123"
}

Part refund with articles​

You can refund part of the order by providing order items, specifying quantity to refund.

Please note

The item object is a best match effort. This means that the more data you provide the probability of finding a unique article will increase. If no unique match can be made an error will be thrown. You should always provide the unitPrice and quantity property.

POST /manage/orders/{{orderId}}/refund HTTP/1.1
Host: api.uat.walleydev.com // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
"amount": 285.0,
"actionReference": "test-refundref-123",
"items": [
{
"id": "10001",
"description": "Shoes",
"unitPrice": 95,
"quantity": 1,
"type": "purchase"
},
{
"id": "10002",
"description": "T-Shirt",
"unitPrice": 95,
"quantity": 2,
"type": "purchase"
}
]
}

Adding Fees​

Additional fees can be added when refunding (eg if you want to add a return-fee or similar).

When adding fees, the amount set should be the total of items + fees.

It is not possible to increase the total order value with fees.

POST /manage/orders/{{orderId}}/refund HTTP/1.1
Host: api.uat.walleydev.com // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
"amount": 75,
"actionReference": "test-refundref-123",
"items": [
{
"id": "10001",
"description": "Shoes",
"unitPrice": 100,
"quantity": 1,
"type": "purchase"
},
{
"id": "10002",
"description": "Return fee",
"unitPrice": -25,
"quantity": 1,
"type": "fee"
}
]
}

Removing Fees​

Fees can be removed when refunding.

When removing fees, the fee should be provided with an positive unit price. The removed fee should also be added into the total refunded amount.

POST /manage/orders/{{orderId}}/refund HTTP/1.1
Host: api.uat.walleydev.com // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
"amount": 125,
"actionReference": "test-refundref-123",
"items": [
{
"id": "10001",
"description": "Shoes",
"unitPrice": 100,
"quantity": 1,
"type": "purchase"
},
{
"id": "10002",
"description": "Return fee",
"unitPrice": 25,
"quantity": 1,
"type": "fee"
}
]
}

Part refund by amount​

You can also perform a partial refund by amount only. This will result in a new line item on the order with a negative value. The adjustment amount will be applied to the most recent capture available on the order.

The 'description' field can be used to provide a descriptive text on the adjustment. If omitted, left blank or null a default value will be used.

POST /manage/orders/{{orderId}}/refund HTTP/1.1
Host: api.uat.walleydev.com // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
"amount": 285.0,
"description": "refund description",
"actionReference": "test-refundref-123"
}

Data Model​

Request​

Request headers​
HeaderRequiredExplanation
AuthorizationYesInstructions on how to generate the Bearer token value can be found here
Request body​
PropertyRequiredExplanation
amountYesThe amount to refund. Must match provided total summary of order items being refunded.
descriptionNoA description for the refund. This will be visible in the order history and on the invoice.
actionReferenceNoA reference to this specific refund. This will be visible on settlement files for reconciliation.
itemsNoThe article items and quantity to refund.

Response​

The response will be 202 Accepted for a successful refund or part refund.

Please note

Due to the asynchronous nature of an Accepted status answer, it can take a few seconds before the update can be shown in various systems and responses to API requests. You should design your system to accomodate this.

Error codes​

CodeMessage
REFUND_AMOUNT_MUST_BE_POSITIVEThe amount that is refunded cant have a negative value
REFUND_AMOUNT_MUST_MATCH_SUM_OF_ARTICLESWhen items are provided, amount must equal to total sum of the items
REFUND_DESCRIPTION_TOO_LONGDescription have a max limit of 50 characters
REFUND_ORDER_ALREADY_FULLY_REFUNDEDYou cannot refund an already fully refunded order
REFUND_ITEM_ID_TOO_LONGItem id has a max limit of 50 characters
REFUND_ITEM_DESCRIPTION_TOO_LONGItem description has a max limit of 50 characters
REFUND_ITEM_QUANTITY_MUST_BE_POSITIVEItem quantity must be positive
UNMATCHED_RETURN_ARTICLESNot all given return articles could be matched
Idempotency

To prevent multiple requests by mistake, the idempotency header can be used to single out requests. The API supports idempotency for safely retrying requests that only should be performed once. This could be useful if responses are not received due to network connectivity problems. For example, if a response for a request to add an invoice is not received, you can retry the request with the same idempotency key again and be guaranteed that no more than one invoice is added.

You will need to generate a guid/uuid v4 and send it in with the header x-idempotency for every unique operation:

X-idempotency: 03304b06-cb33-4f78-bcea-86cb4b202ba0