Refund allocation

When you send the goods in multiple shipments or from multiple locations, you're capturing the order in parts. In these cases, we create separate invoices (payment instructions) for each shipment. For example, instead of receiving one invoice for all ordered goods at once, your customer gets individual invoices for each partial delivery.

We have to pay special attention when your customer asks for a refund and returns only some of the goods. Here, we need to correctly allocate the refund amount to the specific invoice that corresponds to the shipment (capture) of the returned goods.

When your customers return some goods from a partially delivered order, they can expect the refund amount to be allocated to the specific invoice corresponding to that partial delivery.

However, the refund is allocated to the general order and not to the specific invoice that corresponds to the shipment (capture) of the goods, causing confusion for your customers.

We know that correct refund allocation ensures clarity for your customers, but we don't want you to bother with keeping track of capture IDs to correctly allocate refunds.

Instead, you can ensure the correct refund allocation through the use of order lines.

By keeping the order lines consistent between the specific capture and the refund you're making, you help us understand where to allocate the refund.

Specifically, in the request body for capturing an order and in the one for refunding an order, you have to keep exactly the same value in the reference attribute of the order_lines parameter. This is how we can correctly allocate the refund to the right payment instruction.

To help us correctly allocate the refund, you have to:

1. Identify the capture corresponding with the refunds.
2. Ensure the API request contains consistent order lines.
3. Request a refund through the Order management API.

The first step is to identify the specific capture that corresponds to the refunds your customer is requesting.

Let’s say you have received a customer’s order for a T-shirt, a pair of jeans, and a pair of sneakers. You delivered this order in two separate shipments and captured the order in two separate parts:

This is an example of Capture A, including two order lines, one per product:

{
  "captured_amount": 10000,
  "description": "Capture A, shipping part of the order",
  "order_lines": [
  {
    "reference": "A12345",
    "name": "T-shirt",
    "type": "physical",
    "quantity": 1,
    "total_amount": 3000,

This is an example of Capture B, including one order line for a single product:

{
  "captured_amount": 10000,
  "description": "Capture B, shipping the rest of the order",
  "order_lines": [
  {
    "reference": "B24680",
    "name": "Sneakers",
    "type": "physical",
    "quantity": 1,
    "total_amount": 10000,

In this scenario, your customer wants to return the sneakers, so you have to pay attention to Capture B.

Once you identified the correct capture, you have to prepare the refund and ensure you send consistent order lines in your request.

Before you make an API call to refund the order, check that the request body for the refund contains order lines with exactly the same reference attribute as the request body for the capture (in this example, Capture B).

Once you ensured you're sending consistent order lines, you're ready to go with the refund. You have to use our Order management API.

Send a POST request to the {apiUrl}/ordermanagement/v1/orders/{order_id}/refunds endpoint and use the refund request matching the capture.

This is an example of the refund request matching Capture B:

{
  "refunded_amount": 10000,
  "description": "Returning the sneakers",
  "order_lines": [
  {
    "reference": "B24680",
    "name": "Sneakers",
    "type": "physical",
    "quantity": 1,
    "total_amount": 10000,

Allocating refunds correctly is only possible if the orders meet the following conditions:

• The order you're refunding doesn't have any previous refunds with failed allocation.
• The sum of the order lines is exactly equal to the refunded amount.
• The refunded amount is equal to or less than the captured amount in the partial capture you're refunding. In the example above, the refunded amount corresponding to the sneakers cannot be more than the captured_amount in Capture B.

If your refund request doesn't meet these conditions, we'll accept the refund but we won't be able to allocate it to the right invoice.