Manage order lines

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

Use this endpoint to update, cancel, or add one or more order lines. This endpoint sends a single authorisation request that contains the final order lines and amount to the supplier.

Note

You can only update order lines that are created, pending, or authorized.

Example use case

Your customer placed an order that contains two order lines:

  • Order line A contains two items and amounts to €100.00.
  • Order line B contains a discount of 10% applicable to the items in order line A, which amounts to -€10.00.

This means the order amounts to €90.00.

You only have one item A left, and therefore contact your customer to find another solution. The customer opts to replace one of order line A’s items with item C. Item C costs €40.00, however, discount B doesn’t apply to item C.

Using this endpoint, you can create a request to update the order lines.

  • Update order line A’s quantity to 1.
  • Update order line B’s total amount to -€5.00.
  • Add order line C, with a total amount of €40.00.

The updated order amounts to €85.00.

Note

When updating order lines for orders that used a pay after delivery method such as Klarna Pay Later, the supplier (Klarna) may decline the requested changes. This results in an error response from the Mollie API. The order initial remains intact without applying the requested changes.

Parameters

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

Create a request with an array of operations. Each operation must contain an operation field that indicates its type and a data field that contains the operation’s payload.

operationsarray objectrequired

List of operations to be processed.

Show child parameters

operationstringrequired
Operation type. Either add, update, or cancel.
dataobjectrequired

The data object that contains the order line’s details for an update operation. The object should contain all fields that require changes and it must contain at least one parameter, even if all applicable fields are optional.

Show child parameters

namestringoptional
A description of the order line, for example, LEGO 4440 Forest Police Station.
skustringoptional
The SKU, EAN, ISBN, or UPC of the product sold. The maximum character length is 64.
imageUrlstringoptional
A link that points to an image of the product sold.
productUrlstringoptional
A link that points to the sold product’s page in your webshop.
quantityintconditional

The number of items in the order line.

This field is required when the request includes any of the following parameters: unitPrice, discountAmount, totalAmount, vatAmount, or vatRate.

unitPriceamount objectconditional

The price of a single item including VAT in the order line.

For example, {"currency":"EUR", "value":"89.00"} if each box of LEGO costs €89.00.

This can be a negative value if discounts apply, or zero for free items.

This field is required when the request includes any of the following parameters: quantity, discountAmount, totalAmount, vatAmount, or vatRate.

Show child parameters

currencystring
The applicable ISO 4217 currency code.
valuestring
A string that contains the exact amount in the given currency.
discountAmountamount objectoptional

Any discount that applies to the order line. For example, if you want to apply a €10.00 discount: {"currency":"EUR", "value":"10.00"}.

The discountAmount must be a positive value, and is deducted from the (unitPrice × quantity) to calculate the totalAmount of an order line.

See :doc:Handling discounts </orders/handling-discounts> for more information.

Show child parameters

currencystring
The applicable ISO 4217 currency code.
valuestring
A string that contains the exact amount in the given currency.
vatRatestringconditional

The value-added tax (VAT) percentage rate that applies to the order line. You must pass this value as a string instead of a float to ensure that the correct number of decimals are passed. For example, for 21% VAT: "21.00".

This field is required when the request includes any of the following parameters: quantity, unitPrice, discountAmount, totalAmount, or vatAmount.

vatAmountamount objectconditional

The amount of value-added tax (VAT) that applies to the order line. The totalAmount field includes VAT, so you can calculate the vatAmount using the following formula: totalAmount × (vatRate / (100 + vatRate)).

For example, a totalAmount of SEK 100.00 with a 25.00% VAT rate results in SEK 20.00 VAT (100.00 × (25 / 125)). You must pass the vatAmount as an amount object: {"currency":"SEK", "value":"20.00"}.

Deviations from this calculation result in an error.

This field is required when the request includes any of the following parameters: quantity, unitPrice, discountAmount, totalAmount, or vatRate.

Show child parameters

currencystring
The applicable ISO 4217 currency code.
valuestring
A string that contains the exact amount in the given currency.
totalAmountamount objectconditional

The total amount of the order line, including VAT and discounts. For example, if the total amount of an order line is €168.00: {"currency":"EUR", "value":"168.00"}.

The totalAmount should be the result of the following formula: (unitPrice × quantity) - discountAmount.

In addition, the amount top level property should be the sum of all totalAmount values.

This field is required when the request includes any of the following parameters: quantity, unitPrice, discountAmount, vatAmount, or vatRate.

Show child parameters

currencystring
The applicable ISO 4217 currency code.
valuestring
A string that contains the exact amount in the given currency.
metadatamixedoptional
An open field that you can use to provide any other data, for example, a string or a JSON object. The data you provide is saved with the order line. When you fetch it using the API, its metadata is included. You can attach up to approximately 1kB.
dataobjectrequired

The data object that contains the order line’s details for an add operation. The object should contain all fields that are required to create a new order line, which is the same as when you :doc:create an order </reference/v2/orders-api/create-order>.

Show child parameters

typestringoptional

The type of product that was purchased.

Possible values: physical, discount, digital, shipping_fee, store_credit, gift_card, or surcharge.

For more information about discount, store_credit, and gift_card types, see :doc:Handling discounts </orders/handling-discounts>.

To sell digitally delivered goods through PayPal, request PayPal to enable this on your account <https://developer.paypal.com/docs/classic/express-checkout/digital-goods/IntroducingExpressCheckoutDG/>_.

categorystringoptional

The product category.

Possible values: meal, eco, or gift.

If you want to accept voucher payments, at least one of your order lines must contain this field.

namestringrequired
A description of the order line, for example, LEGO 4440 Forest Police Station.
skustringoptional
The SKU, EAN, ISBN, or UPC of the product sold. The maximum character length is 64.
imageUrlstringoptional
A link that points to an image of the product sold.
productUrlstringoptional
A link that points to the sold product’s page in your webshop.
quantityintrequired
The number of items in the order line.
unitPriceamount objectrequired

The price of a single item including VAT in the order line.

For example, {"currency":"EUR", "value":"89.00"} if each box of LEGO costs €89.00.

This can be a negative value if discounts apply, or zero for free items.

Show child parameters

currencystring
The applicable ISO 4217 currency code.
valuestring
A string that contains the exact amount in the given currency.
discountAmountamount objectoptional

Any discount that applies to the order line. For example, if you want to apply a €10.00 discount: {"currency":"EUR", "value":"10.00"}.

The discountAmount must be a positive value, and is deducted from the (unitPrice × quantity) to calculate the totalAmount of an order line.

See :doc:Handling discounts </orders/handling-discounts> for more information.

Show child parameters

currencystring
The applicable ISO 4217 currency code.
valuestring
A string that contains the exact amount in the given currency.
vatRatestringrequired
The value-added tax (VAT) percentage rate that applies to the order line. You must pass this value as a string instead of a float to ensure that the correct number of decimals are passed. For example, for 21% VAT: "21.00"
vatAmountamount objectrequired

The amount of value-added tax (VAT) that applies to the order line. The totalAmount field includes VAT, so you can calculate the vatAmount using the following formula: totalAmount × (vatRate / (100 + vatRate)).

For example, a totalAmount of SEK 100.00 with a 25.00% VAT rate results in SEK 20.00 VAT (100.00 × (25 / 125)). You must pass the vatAmount as an amount object: {"currency":"SEK", "value":"20.00"}.

Deviations from this calculation result in an error.

Show child parameters

currencystring
The applicable ISO 4217 currency code.
valuestring
A string that contains the exact amount in the given currency.
totalAmountamount objectrequired
The total amount of the order line, including VAT and discounts. For example, if the total amount of an order
line is €168.00: {"currency":"EUR", "value":"168.00"}.

The totalAmount should be the result of the following formula: (unitPrice × quantity) - discountAmount.

In addition, the amount top level property should be the sum of all totalAmount values.

Show child parameters

currencystring
The applicable ISO 4217 currency code.
valuestring
A string that contains the exact amount in the given currency.
metadatamixedoptional
An open field that you can use to provide any other data, for example, a string or a JSON object. The data you provide is saved with the order line. When you fetch it using the API, its metadata is included. You can attach up to approximately 1kB.
dataobjectrequired

The data object that contains the order line’s details for a cancel operation. The object should specify the order line and the number of items or the amount that you want to cancel.

Show child parameters

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

The number of items in the order line that you want to cancel. This should be lower than or equal to the number of remaining items in a (partially shipped) order line.

If the quantity is not specified in the request, the entire order line is canceled. For partially shipped order lines, all remaining items are canceled.

amountamount objectoptional

The amount that you want to cancel. In almost all cases, Mollie calculates the amount automatically.

This field is only required when partially canceling an order line that has a discountAmount greater than 0.

The maximum amount you can cancel is unit price x quantity to cancel.

The minimum amount depends on the discount applied to the order line, the quantity of items already shipped or canceled, the amounts already shipped or canceled, and the quantity that you want to cancel.

If the amount is not specified in the request, Mollie automatically calculates the amount. In case it can’t calculate the amount automatically, Mollie returns an error that contains the extra.minimumAmount and extra.maximumAmount properties, enabling you to choose the applicable amount.

Access token parameters

To use organization access tokens or to create an OAuth app, enable test mode using the testmode parameter.

testmodebooleanoptional

Response

200 application/hal+json

Returns an order object.

Example

cURLPHPPythonRubyNode.js
 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
curl -X PATCH https://api.mollie.com/v2/orders/ord_pbjz8x/lines \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" \
   -d '{
          "operations": [
              {
                  "operation": "update",
                  "data": {
                      "id": "odl_1.1l9vx0",
                      "name": "New order line name"
                  }
              },
              {
                  "operation": "cancel",
                  "data": {
                      "id": "odl_1.4hqjw6"
                  }
              },
              {
                  "operation": "add",
                  "data": {
                      "name": "Adding new orderline",
                      "quantity": 2,
                      "sku": "12345679",
                      "totalAmount": {
                          "currency": "EUR",
                          "value": "30.00"
                      },
                      "type": "digital",
                      "unitPrice": {
                          "currency": "EUR",
                          "value": "15.00"
                      },
                      "vatAmount": {
                          "currency": "EUR",
                          "value": "0.00"
                      },
                      "vatRate": "0.00"
                  }
              }
          ]
      }'

1
2
3
4
We don't have a PHP code example for this API call yet.

If you have some time to spare, feel free to share suggestions on our Discord:
https://discord.gg/VaTVkXB4aQ

1
2
3
4
We don't have a Python code example for this API call yet.

If you have some time to spare, feel free to share suggestions on our Discord:
https://discord.gg/VaTVkXB4aQ

1
2
3
4
We don't have a Ruby code example for this API call yet.

If you have some time to spare, feel free to share suggestions on our Discord:
https://discord.gg/VaTVkXB4aQ

1
2
3
4
We don't have a Node.js code example for this API call yet.

If you have some time to spare, feel free to share suggestions on our Discord:
https://discord.gg/VaTVkXB4aQ

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
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
HTTP/1.1 200 OK
Content-Type: application/hal+json

{
 "resource": "order",
 "id": "ord_pbjz8x",
 "profileId": "pfl_h7UgNeDGTA",
 "method": "klarnapaylater",
 "amount": {
     "value": "50.00",
     "currency": "EUR"
 },
 "status": "created",
 "isCancelable": true,
 "metadata": null,
 "createdAt": "2022-06-09T13:49:10+00:00",
 "expiresAt": "2022-07-07T13:49:10+00:00",
 "mode": "live",
 "locale": "en_US",
 "billingAddress": {
     "streetAndNumber": "Herengracht 1",
     "postalCode": "1052CB",
     "city": "Amsterdam",
     "country": "NL",
     "givenName": "mollie",
     "familyName": "test",
     "email": "test@test.com"
 },
 "shopperCountryMustMatchBillingCountry": false,
 "orderNumber": "1",
 "redirectUrl": "https://api.platform.mollielabs.net",
 "webhookUrl": "https://api.platform.mollielabs.net",
 "lines": [
     {
         "resource": "orderline",
         "id": "odl_1.1l9vx0",
         "orderId": "ord_pbjz8x",
         "name": "New orderline name",
         "sku": "123456",
         "type": "digital",
         "status": "created",
         "metadata": null,
         "isCancelable": false,
         "quantity": 2,
         "quantityShipped": 0,
         "amountShipped": {
             "value": "0.00",
             "currency": "EUR"
         },
         "quantityRefunded": 0,
         "amountRefunded": {
             "value": "0.00",
             "currency": "EUR"
         },
         "quantityCanceled": 0,
         "amountCanceled": {
             "value": "0.00",
             "currency": "EUR"
         },
         "shippableQuantity": 0,
         "refundableQuantity": 0,
         "cancelableQuantity": 0,
         "unitPrice": {
             "value": "10.00",
             "currency": "EUR"
         },
         "vatRate": "0.00",
         "vatAmount": {
             "value": "0.00",
             "currency": "EUR"
         },
         "totalAmount": {
             "value": "20.00",
             "currency": "EUR"
         },
         "createdAt": "2022-06-09T13:49:10+00:00"
     },
     {
         "resource": "orderline",
         "id": "odl_1.4hqjw6",
         "orderId": "ord_pbjz8x",
         "name": "A cancelled orderline",
         "sku": "1234444",
         "type": "digital",
         "status": "canceled",
         "metadata": null,
         "isCancelable": true,
         "quantity": 1,
         "quantityShipped": 0,
         "amountShipped": {
             "value": "0.00",
             "currency": "EUR"
         },
         "quantityRefunded": 0,
         "amountRefunded": {
             "value": "0.00",
             "currency": "EUR"
         },
         "quantityCanceled": 1,
         "amountCanceled": {
             "value": "5.00",
             "currency": "EUR"
         },
         "shippableQuantity": 0,
         "refundableQuantity": 0,
         "cancelableQuantity": 0,
         "unitPrice": {
             "value": "5.00",
             "currency": "EUR"
         },
         "vatRate": "0.00",
         "vatAmount": {
             "value": "0.00",
             "currency": "EUR"
         },
         "totalAmount": {
             "value": "5.00",
             "currency": "EUR"
         },
         "createdAt": "2022-06-10T11:05:21+00:00"
     },
     {
         "resource": "orderline",
         "id": "odl_1.3ccpk8",
         "orderId": "ord_pbjz8x",
         "name": "Adding new orderline",
         "sku": "12345679",
         "type": "digital",
         "status": "created",
         "metadata": null,
         "isCancelable": true,
         "quantity": 2,
         "quantityShipped": 0,
         "amountShipped": {
             "value": "0.00",
             "currency": "EUR"
         },
         "quantityRefunded": 0,
         "amountRefunded": {
             "value": "0.00",
             "currency": "EUR"
         },
         "quantityCanceled": 0,
         "amountCanceled": {
             "value": "0.00",
             "currency": "EUR"
         },
         "shippableQuantity": 0,
         "refundableQuantity": 0,
         "cancelableQuantity": 0,
         "unitPrice": {
             "value": "15.00",
             "currency": "EUR"
         },
         "vatRate": "0.00",
         "vatAmount": {
             "value": "0.00",
             "currency": "EUR"
         },
         "totalAmount": {
             "value": "30.00",
             "currency": "EUR"
         },
         "createdAt": "2022-06-10T11:16:49+00:00"
     }
 ],
 "_links": {
     "self": {
         "href": "https://api.mollie.com/v2/orders/ord_xvb27g",
         "type": "application/hal+json"
     },
     "dashboard": {
         "href": "https://www.mollie.com/dashboard/org_2816091/orders/ord_xvb27g",
         "type": "text/html"
     },
     "checkout": {
         "href": "https://www.mollie.com/checkout/order/xvb27g",
         "type": "text/html"
     },
     "documentation": {
         "href": "https://docs.mollie.com/reference/v2/orders-api/get-order",
         "type": "text/html"
     }
 }
}