API & SDKsSupport

Klarna Order Management API (1.0)

Download OpenAPI specification:Download

The Order Management API is used for handling an order after the customer has completed the purchase. It is used for all actions you need to manage your orders. Examples being: updating, capturing, reading and refunding an order.

Read more on the Order management process.

Orders

Get order details

An order that has the given order id. Read more on Retrieving order details

Security
Request
path Parameters
order_id
required
string

Order id

header Parameters
Klarna-Integrator
string
Responses
200

Order found

404

Order not found

get/ordermanagement/v1/orders/{order_id}
Request samples 
Response samples 
application/json
{
  • "billing_address": {
    },
  • "captured_amount": 0,
  • "captures": [
    ],
  • "created_at": "2015-11-29T10:25:40Z",
  • "customer": {
    },
  • "expires_at": "2015-12-04T10:26:06Z",
  • "fraud_status": "ACCEPTED",
  • "initial_payment_method": {
    },
  • "klarna_reference": "K4MADNY",
  • "locale": "en-us",
  • "merchant_data": "Order metadata",
  • "merchant_reference1": "10001",
  • "merchant_reference2": "501",
  • "order_amount": 0,
  • "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  • "order_lines": [
    ],
  • "original_order_amount": 0,
  • "purchase_country": "us",
  • "purchase_currency": "usd",
  • "refunded_amount": 0,
  • "refunds": [
    ],
  • "remaining_authorized_amount": 0,
  • "selected_shipping_option": {
    },
  • "shipping_address": {
    },
  • "shipping_info": [],
  • "status": "AUTHORIZED"
}
Acknowledge a Klarna checkout order
Acknowledge order. Read more on Acknowledging orders


Security 
Request 
path Parameters
order_id
required
string
Order id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Responses 
204
Order was acknowledged.


403
Update not allowed.


404
Order not found.


post/ordermanagement/v1/orders/{order_id}/acknowledge
Request samples 
Response samples 
application/json
{
  • "correlation_id": "66782175-ae05-44fc-9eb3-eeceadbad271",
  • "error_code": "NOT_ALLOWED",
  • "error_messages": [
    ]
}
Update the order amount and order lines
Set new order amount and order lines. Read more on Updating orders


Security 
Request 
path Parameters
order_id
required
string
Order id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Request Body schema: application/json
required
description
string  [ 0 .. 255 ] characters 
Description of the change.


 
order_amount
required
integer <int64>   [ 0 .. 200000000 ] 
The new total order amount. Minor units.


 
Array of objects (order_line)   [ 0 .. 1000 ] items 
New set of order lines for the order.


 
Responses 
204
Authorization was updated.


403
Update authorization not allowed. Decision is based on order state and outcome of risk assessment.


patch/ordermanagement/v1/orders/{order_id}/authorization
Request samples 
application/json
{
  • "description": "Added charger",
  • "order_amount": 200000000,
  • "order_lines": [
    ]
}
Response samples 
application/json
"string"
Update customer addresses
Update shipping address. Read more on Updating customer addresses


Security 
Request 
path Parameters
order_id
required
string
Order id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Request Body schema: application/json
required
object (address) 
Shipping address for the capture.


 
Responses 
204
Order consumer details were updated.


403
Update customer details not allowed. Decision is based on order state and outcome of risk assessment. Billing address cannot be updated.


patch/ordermanagement/v1/orders/{order_id}/customer-details
Request samples 
application/json
{
  • "shipping_address": {
    }
}
Response samples 
application/json
"string"
Extend the authorization time
Extend authorization time. Read more on Extending order authorization time


Security 
Request 
path Parameters
order_id
required
string
Order id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Responses 
204
Authorization time was extended.


403
Extension of authorization time not allowed. The order being expired or cancelled are among the possible causes.


post/ordermanagement/v1/orders/{order_id}/extend-authorization-time
Request samples 
Response samples 
application/json
{
  • "correlation_id": "66782175-ae05-44fc-9eb3-eeceadbad271",
  • "error_code": "NOT_ALLOWED",
  • "error_messages": [
    ]
}
Update merchant references
Update merchant references. Read more on Updating merchant references


Security 
Request 
path Parameters
order_id
required
string
Order id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Request Body schema: application/json
required
merchant_reference1
string  [ 0 .. 255 ] characters 
New merchant reference 1. Old reference will be overwritten if this field is present.


 
merchant_reference2
string  [ 0 .. 255 ] characters 
New merchant reference 2. Old reference will be overwritten if this field is present.


 
Responses 
204
Order merchant references were updated.


403
Can not update a cancelled order.


patch/ordermanagement/v1/orders/{order_id}/merchant-references
Request samples 
application/json
{
  • "merchant_reference1": "string",
  • "merchant_reference2": "string"
}
Response samples 
application/json
{
  • "correlation_id": "66782175-ae05-44fc-9eb3-eeceadbad271",
  • "error_code": "NOT_ALLOWED",
  • "error_messages": [
    ]
}
Release an authorization
Release remaining authorization. Read more on Releasing remaining authorization


Security 
Request 
path Parameters
order_id
required
string
Order id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Responses 
204
Remaining authorization was released.


403
Can not release when order is cancelled or has no captures.


post/ordermanagement/v1/orders/{order_id}/release-remaining-authorization
Request samples 
Response samples 
application/json
"string"
Add shipping information
Add shipping info to an order. Read more on Adding shipping info


Security 
Request 
path Parameters
order_id
required
string
Order id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Request Body schema: application/json
required
required
Array of objects (shipping_info)   [ 1 .. 500 ] items 
New shipping info. Maximum: 500 items.


 
Responses 
204
Shipping information was appended.


404
Order not found.


post/ordermanagement/v1/orders/{order_id}/shipping-info
Request samples 
application/json
{}
Response samples 
application/json
{
  • "correlation_id": "66782175-ae05-44fc-9eb3-eeceadbad271",
  • "error_code": "NO_SUCH_ORDER",
  • "error_messages": [
    ]
}
Cancel an order
Cancel order. Read more on Cancelling an order


Security 
Request 
path Parameters
order_id
required
string
Order id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Responses 
204
Order was cancelled.


403
Cancel not allowed (e.g. order has captures or is closed)


post/ordermanagement/v1/orders/{order_id}/cancel
Request samples 
Response samples 
application/json
{
  • "correlation_id": "66782175-ae05-44fc-9eb3-eeceadbad271",
  • "error_code": "CANCEL_NOT_ALLOWED",
  • "error_messages": [
    ]
}
Captures
Capture an order
Create capture. Read more on Capturing an order


Security 
Request 
path Parameters
order_id
required
string
Order id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Request Body schema: application/json
required
captured_amount
required
integer <int64>   [ 0 .. 200000000 ] 
The captured amount in minor units.


 
description
string  [ 0 .. 255 ] characters 
Description of the capture shown to the customer. Maximum 255 characters.


 
Array of objects (order_line)   [ 0 .. 1000 ] items 
Order lines for this capture. Maximum 1000 items.


 
reference
string  [ 0 .. 255 ] characters 
Internal reference to the capture. This will be included in the settlement files. Max length is 255 characters.


 
shipping_delay
integer <int64>   >= 0 
Delay before the order will be shipped. Use for improving the customer experience regarding payments. This field is currently not returned when reading the order. Minimum: 0. Please note: to be able to submit values larger than 0, this has to be enabled in your merchant account. Please contact Klarna for further information.


 
Array of objects (shipping_info)   [ 0 .. 500 ] items 
Shipping information for this capture. Maximum 500 items.


 
Responses 
201
Capture created


403
Capture not allowed.


404
Order not found.


post/ordermanagement/v1/orders/{order_id}/captures
Request samples 
application/json
{
  • "captured_amount": 200000000,
  • "description": "string",
  • "order_lines": [
    ],
  • "reference": "string",
  • "shipping_delay": 0,
  • "shipping_info": []
}
Response samples 
application/json
{
  • "correlation_id": "66782175-ae05-44fc-9eb3-eeceadbad271",
  • "error_code": "CAPTURE_NOT_ALLOWED",
  • "error_messages": [
    ]
}
List all order captures
List all order captures


Security 
Request 
path Parameters
order_id
required
string
Order id


 
Responses 
200
Captures found.


404
Order not found.


get/ordermanagement/v1/orders/{order_id}/captures
Request samples 
Response samples 
application/json
[
  • {
    }
]
Get capture details
Retrieve the details of a capture. To learn more, refer to the Retrieving capture details article.


Security 
Request 
path Parameters
order_id
required
string
Order id


 
capture_id
required
string
Capture id


 
Responses 
200
Capture found.


404
Order or capture not found.


get/ordermanagement/v1/orders/{order_id}/captures/{capture_id}
Request samples 
Response samples 
application/json
{
  • "billing_address": {
    },
  • "capture_id": "4ba29b50-be7b-44f5-a492-113e6a865e22",
  • "captured_amount": 1,
  • "captured_at": "2015-11-19T01:51:17Z",
  • "description": "Order has been shipped",
  • "klarna_reference": "K4MADNY-1",
  • "order_lines": [
    ],
  • "reference": "string",
  • "refunded_amount": 0,
  • "shipping_address": {
    },
  • "shipping_info": []
}
Extend payment due date
Extend the customer's payment due date. Read more on Extending customer due dates


Security 
Request 
path Parameters
order_id
required
string
Order id


 
capture_id
required
string
Capture id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Request Body schema: application/json
required
number_of_days
required
integer <int32> 
Number of days to extend the due date.


 
Responses 
204
Due date was extended.


403
Extension of due date is not possible.


404
Order or capture not found.


patch/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/extend-due-date
Request samples 
application/json
{
  • "number_of_days": 0
}
Response samples 
application/json
{
  • "correlation_id": "string",
  • "error_code": "string",
  • "error_messages": [
    ]
}
List options for extension of payment due date
Get merchant fees for extension of due date due date


Security 
Request 
path Parameters
order_id
required
string
Order id


 
capture_id
required
string
Capture id


 
Responses 
200
Available options found for capture.


404
Order or capture not found.


get/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/extend-due-date-options
Request samples 
Response samples 
application/json
{
  • "currency": "usd",
  • "options": [
    ]
}
Add shipping information
Add shipping info to a capture. Read more on Adding shipping info


Security 
Request 
path Parameters
order_id
required
string
Order id


 
capture_id
required
string
Capture id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Request Body schema: application/json
required
required
Array of objects (shipping_info)   [ 1 .. 500 ] items 
New shipping info. Maximum: 500 items.


 
Responses 
204
Shipping information was appended.


403
Order has no captures.


404
Order or capture not found.


post/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/shipping-info
Request samples 
application/json
{}
Response samples 
application/json
{
  • "correlation_id": "66782175-ae05-44fc-9eb3-eeceadbad271",
  • "error_code": "NOT_ALLOWED",
  • "error_messages": [
    ]
}
Send customer communication
Trigger resend of customer communication. Read more on Resending customer communication


Security 
Request 
path Parameters
order_id
required
string
Order id


 
capture_id
required
string
Capture id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Responses 
204
Send out was triggered


403
Order has no captures.


404
Order or capture not found.


post/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/trigger-send-out
Request samples 
Response samples 
application/json
{
  • "correlation_id": "66782175-ae05-44fc-9eb3-eeceadbad271",
  • "error_code": "NOT_ALLOWED",
  • "error_messages": [
    ]
}
Refunds
Refund an order
Create a refund. Read more on Refunds


Security 
Request 
path Parameters
order_id
required
string
Order id


 
header Parameters
Klarna-Idempotency-Key
string
This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.


 
Request Body schema: application/json
required
description
string  [ 0 .. 255 ] characters 
Description of the refund shown to the customer. Max length is 255 characters.


 
Array of objects (order_line)   [ 0 .. 1000 ] items 
Order lines for the refund shown to the customer. Optional but increases the customer experience. Maximum 1000 order lines.


 
reference
string  [ 0 .. 255 ] characters 
Internal reference to the refund. This will be included in the settlement files. Max length is 255 characters.


 
refunded_amount
required
integer <int64>   [ 0 .. 200000000 ] 
Refunded amount in minor units.


 
Responses 
201
Refund created


403
Refund not allowed


404
Order not found.


post/ordermanagement/v1/orders/{order_id}/refunds
Request samples 
application/json
{
  • "description": "string",
  • "order_lines": [
    ],
  • "reference": "string",
  • "refunded_amount": 200000000
}
Response samples 
application/json
"string"
Get refund details
Get refund. 


Security 
Request 
path Parameters
order_id
required
string
Order id


 
refund_id
required
string
Refund id


 
Responses 
200
Refund found.


404
Order or refund not found.


get/ordermanagement/v1/orders/{order_id}/refunds/{refund_id}
Request samples 
Response samples 
application/json
{
  • "credit_invoice": true,
  • "description": "The item was returned and the order refunded.",
  • "order_lines": [
    ],
  • "reference": "string",
  • "refund_id": "b2cb4f2e-2781-4359-80ad-555735ebb8d8",
  • "refunded_amount": 0,
  • "refunded_at": "2015-12-04T15:17:40Z"
}
Cookies
Terms of Service
© Klarna 2024