updateOrder
HTTP method: POST
Use the updateOrder to update the order amount, add, remove or update order lines and update order details.
The following diagram describes a typical updateOrder flow using the Merchant API.
Select one of the payment methods that supports update order to see the parameters relevant for that method:
Parameter | Description | Type | Mandatory | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
payment_id |
The id of a specific payment. |
[0-9a-f]{1,32} | Yes | ||||||||||||||
amount |
This is the gross amount to be updated to (including taxes). In cases of invoice payments it should match the gross total amount of order lines. You must use a dot as the decimal separator, and the amount can have maximum 2 decimals. |
float | Yes - It can be optional when transaction_info is provided | ||||||||||||||
orderLines | Listing of order lines. (Only relevant for invoice payment methods such as KlarnaPayments) |
Array See table below |
No
In case it's not passed, it will remove all the order lines
|
||||||||||||||
transaction_info |
This is a one-dimensional associative array, where you can put any value that you would like to associate with the payment in the call to createPaymentRequest. |
Array Maximum 50 entries of maximum 255 characters each. |
No |
||||||||||||||
customer_info | Listing of customer info for updating shipping details. (Only relevant for KlarnaPayments) |
Array See table below |
No
In case it's not passed, it will not do anything
|
||||||||||||||
trackingInfo[] |
Tracking information, in an array. Could include:
trackingInfo[0][trackingId] = 1
trackingInfo[0][companyName] = Mærsk trackingInfo[0][method] = PickUpStore trackingInfo[0][trackingNumber] = 123abc trackingInfo[0][trackingUri] = www.tracking.com/id trackingInfo[0][type] = SHIPPING trackingInfo[1][trackingId] = 2 trackingInfo[1][refTrackingId] = 1 trackingInfo[1][companyName] = ReturnCo trackingInfo[1][trackingNumber] = 456abc trackingInfo[1][trackingUri] = www.tracking.com/id2 trackingInfo[1][type] = RETURN See https://docs.klarna.com/api/ordermanagement/#operation/captureOrder Please make sure you passed same number of tracking info of SHIPPING type with the RETURN type so that it can be mapped correctly with the KlarnaPayments shipping_info |
Array |
No
In case it's not passed, it will not do anything
|
Order lines
Parameter | Description | Type | Mandatory |
---|---|---|---|
orderLines | The individual line items of the order. | Array |
Yes
|
For each order line:
Value |
Description |
Type |
Mandatory |
---|---|---|---|
description |
Description of an item. |
String (255) |
Yes |
itemId |
The item identification. Each itemId must be unique within an order. |
String (100) |
Yes |
quantity |
The quantity of the item. The value must be greater than zero. |
Decimal |
Yes |
unitPrice |
The unit price, excluding sales tax. The value must be greater than zero, unless the optional goodsType parameter is set to handling, in which case the field can be used to provide a discount. |
Decimal |
Yes |
taxPercent |
This is the tax percentage of the unit price. Send both the taxPercent and taxAmount parameters in the method call. If you provide only one, the other is inferred, and rounding errors may occur. The taxAmount is used for the calculation, and taxPercent is printed on the invoice.
|
Decimal |
No |
taxAmount |
This is the total tax on an order line, before any discounts are applied. It is recommended to use taxAmount if possible. If you provide both taxPercent and taxAmount, the amount takes precedence. Send both the taxPercent and taxAmount parameters in the method call. If you provide only one of the taxPercent and taxAmount parameters, the other parameter is inferred, and rounding errors may occur.
The taxAmount is used for the calculation, and taxPercent is printed on the invoice. |
Decimal |
Yes |
unitCode |
The relevant measurement unit for the order line. For example, kg. |
String (50) |
|
discount |
The order line's discount in percent. |
Decimal |
|
goodsType |
The goods type of the order line - shipment | handling | item | digital | discount | gift_card| physical | sales_tax |
||
imageUrl |
The full URL of the icon for the item |
String (255) |
|
productUrl | The full URL for the description of the item | String (255) |
Customer Info (Only KlarnaPayments)
If you wish to update shipping information in addition to general payment information, then please provide the following format for customer_info parameters as seen in Create Payment Request's Customer information parameters section.
The relevant fields for the updateOrder call with KlarnaPayments are: shipping_lastname, shipping_firstname, shipping_address, shipping_postal, shipping_region, shipping_country, shipping_city, email, customer_phone and company_name
In case of failure during the updateOrder call you may receive a PartialSuccess response, meaning that general payment information was updated but shipping information failed to update. The reason will be provided in <MerchantErrorMessage> in the response.
The table shows the most pertinent response values for the method. For a complete list of API response parameters, see API Response structure (XML).
Parameter | Description | Type |
---|---|---|
Result | Success, PartialSuccess or Error. | string |
Test URL | https://testgateway.altapaysecure.com/merchant/API/<method> |
Production URL | https://<YourShopName>.altapaysecure.com/merchant/API/<method> |
Request
curl --request POST \ --url https://<YourShopName>.altapaysecure.com/merchant/API/updateOrder \ --header 'Authorization: Basic auth' \ --data payment_id=55 \ --data amount=144.70 \ --data `orderLines[0][description]`=Product1 \ --data `orderLines[0][itemId]`=abc123 \ --data `orderLines[0][quantity]`=2 \ --data `orderLines[0][taxAmount]`=10.00 \ --data `orderLines[0][unitCode]`=pcs \ --data `orderLines[0][unitPrice]`=20.00 \ --data `orderLines[0][discount]`=5 \ --data `orderLines[1][description]`=Product2 \ --data `orderLines[1][itemId]`=def456 \ --data `orderLines[1][quantity]`=3 \ --data `orderLines[1][taxPercent]`=8 \ --data `orderLines[1][unitCode]`=pcs \ --data `orderLines[1][unitPrice]`=30.00 \ --data `orderLines[1][discount]`=0 \
XML result
<?xml version="1.0" encoding="utf-8" ?> <APIResponse version="20170228"> <Header> <Date>2020-09-29T12:34:56+02:00</Date> <Path>API/updateOrder</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>Success</Result> </Body> </APIResponse>
Partial Success Result Example
<?xml version="1.0"?> <APIResponse version="20170228"> <Header> <Date>2023-06-28T08:49:16+00:00</Date> <Path>API/updateOrder</Path> <ErrorCode>0</ErrorCode> <ErrorMessage/> </Header> <Body> <Result>PartialSuccess</Result> <MerchantErrorMessage>Partial Error in [Update Customer Details]: UNPROCESSABLE_ENTITY ['shipping_address.postal_code' size must be between 0 and 10 (was 19)]</MerchantErrorMessage> <MerchantErrorCode>240000</MerchantErrorCode> <CardHolderMessageMustBeShown>false</CardHolderMessageMustBeShown> </Body> </APIResponse>
You can update the order multiple times. To do this you should call the updateOrder method with the same payment_id as many times as you want.
If your request comes with partial success response, you can create a new request fixing the parameters in question and send the new request.
The provided order lines in the request will replace the existing order lines of an order.
The amount value should be equal to the total amount of the order lines.
The amount value cannot be smaller or equal to the captured amount.
The following formula describe how the total amount is calculated
Order line net-amount = quantity * unitPrice Order line tax-amount = taxAmount if the parameter is sent in the request OR taxPercent * net-amount / 100 Order line gross-amount = net-amount + tax-amount Order line discount-amount = discount * gross-amount / 100 Order line gross-amount-with-discount = gross-amount - discount-amount Total amount = sum of gross-amount-with-discount of all the order lines