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.

Request

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"
}

Response

Status: 202 Accepted

/* Headers */
Location: /manage/orders/1b1f5ef6-92n1-4b46-b1dc-ae2e00c4c315

/* No body */

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.

Request

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"
    }
  ]
}

Response

Status: 202 Accepted

/* Headers */
Location: /manage/orders/1b1f5ef6-92n1-4b46-b1dc-ae2e00c4c315

/* No body */

Adding Fees

Additional fees can be added when refunding (e.g. If you would like to add a return-fee or similar).

• Added fees needs to have the vat property set, otherwise it will default to 0.
• 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.

Request

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,
      "vat": 25,
      "type": "purchase"
    },
    {
      "id": "10002",
      "description": "Return fee",
      "unitPrice": -25,
      "quantity": 1,
      "vat": 25,
      "type": "fee"
    }
  ]
}

Response

Status: 202 Accepted

/* Headers */
Location: /manage/orders/1b1f5ef6-92n1-4b46-b1dc-ae2e00c4c315

/* No body */

Adding Discounts

Discounts can be added to a refund request to give back money at the same time as refunding.

• Added discounts needs to have the vat property set, otherwise it will default to 0.
• Discounts should be added with a positive unit price.
• It is not possible to decrease the total order value with discounts below 0.
• When adding discounts, the amount set should be the total of items + discounts.
• Discounts can be combined with fees.

Request

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

{
  "amount": 150,
  "actionReference": "test-refundref-123",
  "items": [
    {
      "id": "10001",
      "description": "Shoes",
      "unitPrice": 100,
      "quantity": 1,
      "type": "purchase"
    },
    {
      "id": "32455",
      "description": "Discount-50-sale",
      "unitPrice": 50,
      "quantity": 1,
      "vat": 25,
      "type": "discount"
    }
  ]
}

Response

Status: 202 Accepted

/* Headers */
Location: /manage/orders/1b1f5ef6-92n1-4b46-b1dc-ae2e00c4c315

/* No body */

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.

Request

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,
      "vat": 25,
      "type": "purchase"
    },
    {
      "id": "10002",
      "description": "Return fee",
      "unitPrice": 25,
      "quantity": 1,
      "vat": 25,
      "type": "fee"
    }
  ]
}

Response

Status: 202 Accepted

/* Headers */
Location: /manage/orders/1b1f5ef6-92n1-4b46-b1dc-ae2e00c4c315

/* No body */

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.

Request

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"
}

Response

Status: 202 Accepted

/* Headers */
Location: /manage/orders/1b1f5ef6-92n1-4b46-b1dc-ae2e00c4c315

/* No body */

Http status code	Description
202	Order refunded
401	Unauthorized, token verification needed. See: Authentication for more information
403	Permissions needed e.g. trying to handle content for a store you don't have permission to
404	Order not found
422	See error codes

Data Model

Request

Request headers

Header	Required	Explanation
Authorization	Yes	Instructions on how to generate the Bearer token value can be found here

Request body

Property	Required	Explanation	Type	Notes
amount	Yes	The amount to refund. Must match provided total summary of order items being refunded.	number	Maximum 2 decimals
description	No	A description for the refund. This will be visible in the order history and on the invoice.	string	Visible on invoices if applicable. Maximum 50 characters
actionReference	No	A reference to this specific refund. This will be visible on settlement files for reconciliation.	string	This will appear as a data property on the settlement report
items	No	The article items and quantity to refund.	array	Refund Item

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

Code	Message
REFUND_AMOUNT_MUST_BE_POSITIVE	The amount that is refunded cant have a negative value
REFUND_AMOUNT_MUST_MATCH_SUM_OF_ARTICLES	When items are provided, amount must equal to total sum of the items
REFUND_DESCRIPTION_TOO_LONG	Description have a max limit of 50 characters
REFUND_ORDER_ALREADY_FULLY_REFUNDED	You cannot refund an already fully refunded order
REFUND_UNMATCHED_RETURN_ARTICLES	Items provided for part refund can't be found on order. The provided values for id, description and unitprice must match the order item values exactly.
REFUND_AMOUNT_HAS_TOO_MANY_DECIMALS	The amount to be refunded has too many decimals
REFUND_VAT_HAS_TOO_MANY_DECIMALS	The VAT rate given has too many decimals
REFUND_ITEM_ID_TOO_LONG	Item id has a max limit of 50 characters
REFUND_ITEM_DESCRIPTION_TOO_LONG	Item description has a max limit of 50 characters
REFUND_ITEM_QUANTITY_MUST_BE_POSITIVE	Item quantity must be positive
REFUND_ITEM_UNITPRICE_HAS_TOO_MANY_DECIMALS	Item Unit Price has too many decimals
REFUND_ITEM_FEE_OR_DISCOUNT_ID_AND_DESCRIPTION_REQUIRED	Fees and discounts must have an id and a description

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