Manage order lines¶
PATCH
https://api.mollie.com/v2/orders/*orderId*/lines
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.
operations
array objectrequiredList of operations to be processed.
operation
stringrequiredadd
, update
, or cancel
.data
objectrequiredThe 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.
name
stringoptionalsku
stringoptionalimageUrl
stringoptionalproductUrl
stringoptionalquantity
intconditionalThe 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
.
unitPrice
amount objectconditionalThe 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
.
currency
stringvalue
stringdiscountAmount
amount objectoptionalAny 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.
currency
stringvalue
stringvatRate
stringconditionalThe 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
.
vatAmount
amount objectconditionalThe 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
.
currency
stringvalue
stringtotalAmount
amount objectconditionalThe 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
.
currency
stringvalue
stringmetadata
mixedoptionaldata
objectrequiredThe 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>.
type
stringoptionalThe 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/>_.
category
stringoptionalThe 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.
name
stringrequiredsku
stringoptionalimageUrl
stringoptionalproductUrl
stringoptionalquantity
intrequiredunitPrice
amount objectrequiredThe 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.
currency
stringvalue
stringdiscountAmount
amount objectoptionalAny 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.
currency
stringvalue
stringvatRate
stringrequired"21.00"
vatAmount
amount objectrequiredThe 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.
currency
stringvalue
stringtotalAmount
amount 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.
currency
stringvalue
stringmetadata
mixedoptionaldata
objectrequiredThe 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.
id
stringrequiredodl_jp31jz
.quantity
intoptionalThe 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.
amount
amount objectoptionalThe 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.
testmode
to true
to update an order line that was created in test mode.Example¶
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" } } } |