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

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

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

Replacement article​

To replace a refunded article, add an article of type 'replacement' without increasing the total order amount.

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

{
  "amount": 20,
  "items": [
    {
      "id": "10001",
      "description": "Shoes",
      "unitPrice": 100,
      "quantity": 1,
      "vat": 25,
      "type": "purchase"
    },
    {
      "id": "10002",
      "description": "Shoes",
      "unitPrice": -80,
      "quantity": 1,
      "vat": 25,
      "type": "replacement"
    },
  ]
}

Data Model​

Request​

Request path​
PathRequiredExplanation
orderIdYesThe id off the order where a refund is to be carried out
Request headers​
HeaderRequiredExplanation
AuthorizationYesInstructions on how to generate the Bearer token value can be found here
Request body​
PropertyRequiredExplanationTypeNotes
amountYesThe amount to refund. Must match provided total summary of order items being refunded.numberMaximum 2 decimals
descriptionNoA description for the refund. This will be visible in the order history and on the invoice.stringVisible on invoices if applicable. Maximum 50 characters
actionReferenceNoA reference to this specific refund. This will be visible on settlement files for reconciliation.stringThis will appear as a data property on the settlement report
itemsNoThe article items and quantity to refund.arrayRefund 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.

Possible responses​

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

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_UNMATCHED_RETURN_ARTICLESItems 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_DECIMALSThe amount to be refunded has too many decimals
REFUND_VAT_HAS_TOO_MANY_DECIMALSThe VAT rate given has too many decimals
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
REFUND_ITEM_UNITPRICE_HAS_TOO_MANY_DECIMALSItem Unit Price has too many decimals
REFUND_ITEM_FEE_OR_DISCOUNT_ID_AND_DESCRIPTION_REQUIREDFees and discounts must have an id and a description
REFUND_REPLACEMENT_ITEM_QUANTITY_INVALIDWhen processing a refund and a replacement for the same item within a single request, the replacement quantity cannot exceed the refund quantity
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