Create order refund

Orders API v2
POSThttps://api.mollie.com/v2/orders/*orderId*/refunds
Authentication:API keysOrganization access tokensApp access tokens

When using the Orders API, refunds should be made for a specific order.

If you want to refund arbitrary amounts, however, you can also use the Create payment refund endpoint for Pay later and Slice it by creating a refund on the payment itself.

If an order line is still in the authorized status, it cannot be refunded. You should cancel it instead. Order lines that are paid, shipping or completed can be refunded.

For more details on how refunds work, see Refunds.

Parameters

Replace orderId in the endpoint URL by the order’s ID, for example ord_8wmqcHMN4U.

linesarrayrequired

An array of objects containing the order line details you want to create a refund for. If you send an empty array, the entire order will be refunded.

Hide child parameters

idstringrequired
The API resource token of the order line, for example: odl_jp31jz.
quantityintoptional

The number of items that should be refunded for this order line. When this parameter is omitted, the whole order line will be refunded.

Must be less than the number of items already refunded for this order line.

amountamount objectoptional

The amount that you want to refund. In almost all cases, Mollie can determine the amount automatically.

The amount is required only if you are partially refunding an order line which has a non-zero discountAmount.

The amount you can refund depends on various properties of the order line and the create order refund request. The maximum that can be refunded is unit price x quantity to ship.

The minimum amount depends on the discount applied to the line, the quantity already refunded or shipped, the amounts already refunded or shipped and the quantity you want to refund.

If you do not send an amount, Mollie will determine the amount automatically or respond with an error if the amount cannot be determined automatically. The error will contain the extra.minimumAmount and extra.maximumAmount properties that allow you pick the right amount.

Show child parameters

currencystringrequired
An ISO 4217 currency code. The currency must be the same as the corresponding payment.
valuestringrequired
A string containing the exact amount you want to refund in the given currency. Make sure to send the right amount of decimals. Non-string values are not accepted.
descriptionstringoptional
The description of the refund you are creating. This will be shown to the consumer on their card or bank statement when possible. Max. 140 characters.
metadatamixedoptional
Provide any data you like, for example a string or a JSON object. We will save the data alongside the refund. Whenever you fetch the refund with our API, we will also include the metadata. You can use up to approximately 1kB.

Access token parameters

If you are using organization access tokens or are creating an OAuth app, you can enable test mode through the testmode parameter.

testmodebooleanoptional

Response

201 application/hal+json

An refund object is returned, as described in Get payment refund.

Example

cURLPHPPythonRubyNode.js
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
curl -X POST https://api.mollie.com/v2/orders/ord_stTC2WHAuS/refunds \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
   -d '{
            "lines": [
               {
                  "id": "odl_dgtxyl",
                  "quantity": 1
               }
            ],
            "description": "Required quantity not in stock, refunding one photo book.",
            "metadata": {
               "bookkeeping_id": 12345
            }
   }'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<?php
$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setApiKey("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM");

$order = $mollie->orders->get("ord_stTC2WHAuS");
$order->refund([
      'lines' => [
         [
            'id' => 'odl_dgtxyl',
            'quantity' => 1,
         ],
      ],
      "description" => "Required quantity not in stock, refunding one photo book.",
]);

// Alternative shorthand for refunding all eligible order lines
$order->refundAll([
      "description" => "Required quantity not in stock, refunding one photo book.",
]);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
mollie_client = Client()
mollie_client.set_api_key("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM")

order = mollie_client.orders.get("ord_stTC2WHAuS")
refund = order.refunds.create({
    "lines": [
        "id": "odl_dgtxyl",
        "quantity": 1,
    ],
    "description": "Required quantity not in stock, refunding one photo book.",
})

# Alternative shorthand for refunding all eligible order lines
refund = order.refunds.create()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
require 'mollie-api-ruby'

Mollie::Client.configure do |config|
  config.api_key = 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM'
end

order  = Mollie::Order.get('ord_stTC2WHAuS')
refund = order.refund!(
  lines: [
    {
      id: 'odl_dgtxyl',
      quantity: 1
    }
  ],
  description: 'Required quantity not in stock, refunding one photo book.'
)

# Alternative shorthand for refunding all eligible order lines
order.refund!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const { createMollieClient } = require('@mollie/api-client');
const mollieClient = createMollieClient({ apiKey: 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM' });

const refund = await mollieClient.orderRefunds.create({
  orderId: 'ord_stTC2WHAuS',
  lines: [{
    id: 'odl_dgtxyl',
    quantity: 1
  }],
  description: 'Required quantity not in stock, refunding one photo book.'
});

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
HTTP/1.1 201 Created
Content-Type: application/hal+json

{
    "resource": "refund",
    "id": "re_4qqhO89gsT",
    "amount": {
        "currency": "EUR",
        "value": "698.00"
    },
    "status": "pending",
    "createdAt": "2018-03-14T17:09:02.0Z",
    "description": "Required quantity not in stock, refunding one photo book.",
    "metadata": {
         "bookkeeping_id": 12345
    },
    "paymentId": "tr_WDqYK6vllg",
    "orderId": "ord_stTC2WHAuS",
    "lines": [
        {
            "resource": "orderline",
            "id": "odl_dgtxyl",
            "orderId": "ord_stTC2WHAuS",
            "name": "LEGO 42083 Bugatti Chiron",
            "sku": "5702016116977",
            "type": "physical",
            "status": "paid",
            "metadata": null,
            "quantity": 1,
            "unitPrice": {
                "value": "399.00",
                "currency": "EUR"
            },
            "vatRate": "21.00",
            "vatAmount": {
                "value": "51.89",
                "currency": "EUR"
            },
            "discountAmount": {
                "value": "100.00",
                "currency": "EUR"
            },
            "totalAmount": {
                "value": "299.00",
                "currency": "EUR"
            },
            "createdAt": "2018-08-02T09:29:56+00:00",
            "_links": {
                "productUrl": {
                    "href": "https://shop.lego.com/nl-NL/Bugatti-Chiron-42083",
                    "type": "text/html"
                },
                "imageUrl": {
                    "href": "https://sh-s7-live-s.legocdn.com/is/image//LEGO/42083_alt1?$main$",
                    "type": "text/html"
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "https://api.mollie.com/v2/payments/tr_WDqYK6vllg/refunds/re_4qqhO89gsT",
            "type": "application/hal+json"
        },
        "payment": {
            "href": "https://api.mollie.com/v2/payments/tr_WDqYK6vllg",
            "type": "application/hal+json"
        },
        "order": {
            "href": "https://api.mollie.com/v2/orders/ord_stTC2WHAuS",
            "type": "application/hal+json"
        },
        "documentation": {
            "href": "https://docs.mollie.com/reference/v2/refunds-api/create-order-refund",
            "type": "text/html"
        }
    }
}

Response (amount required)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/hal+json

{
     "status": 422,
     "title": "Unprocessable Entity",
     "detail": "Line 0 contains invalid data. An amount is required for this API call. The amount must be between €0.00 and €50.00.",
     "field": "lines.0.amount",
     "extra": {
         "minimumAmount": {
             "value": "0.00",
             "currency": "EUR"
         },
         "maximumAmount": {
             "value": "50.00",
             "currency": "EUR"
         }
     },
     "_links": {
         "documentation": {
             "href": "https://docs.mollie.com/reference/v2/refunds-api/create-order-refund",
             "type": "text/html"
         }
     }
 }