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.

Authentication

Basic authorization

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Orders

Get order details

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

Request
Security:
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
curl -i -X GET \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}' \
  -H 'Klarna-Integrator: string'
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

Request
Security:
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
curl -i -X POST \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/acknowledge' \
  -H 'Klarna-Idempotency-Key: string'
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

Request
Security:
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
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

Request
Security:
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
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

Request
Security:
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
curl -i -X POST \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/extend-authorization-time' \
  -H 'Klarna-Idempotency-Key: string'
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

Request
Security:
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
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

Request
Security:
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
curl -i -X POST \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/release-remaining-authorization' \
  -H 'Klarna-Idempotency-Key: string'
Response samples
application/json
"string"

Add shipping information

Add shipping info to an order. Read more on Adding shipping info

Request
Security:
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
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

Request
Security:
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
curl -i -X POST \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/cancel' \
  -H 'Klarna-Idempotency-Key: string'
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

Request
Security:
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
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

Request
Security:
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
curl -i -X GET \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/captures'
Response samples
application/json
[
  • {
    }
]

Get capture details

Retrieve the details of a capture. To learn more, refer to the Retrieving capture details article.

Request
Security:
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
curl -i -X GET \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/captures/{capture_id}'
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

Request
Security:
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
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

Request
Security:
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
curl -i -X GET \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/extend-due-date-options'
Response samples
application/json
{
  • "currency": "usd",
  • "options": [
    ]
}

Add shipping information

Add shipping info to a capture. Read more on Adding shipping info

Request
Security:
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
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

Request
Security:
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
curl -i -X POST \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/trigger-send-out' \
  -H 'Klarna-Idempotency-Key: string'
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

Request
Security:
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
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.

Request
Security:
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
curl -i -X GET \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/refunds/{refund_id}'
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