Order Management API (1.0)

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.

Download OpenAPI description
Languages
Servers
https://api.klarna.com/

Orders

Operations

Captures

Operations

Capture an order

Request

Path
order_idstringrequired

Order id

Headers
Klarna-Idempotency-Keystring

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.

Bodyapplication/jsonrequired
captured_amountinteger(int64)[ 0 .. 200000000 ]required

The captured amount in minor units.

descriptionstring[ 0 .. 255 ] characters

Description of the capture shown to the customer. Maximum 255 characters.

order_linesArray of objects(order_line)[ 0 .. 1000 ] items

Order lines for this capture. Maximum 1000 items.

referencestring[ 0 .. 255 ] characters

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

shipping_delayinteger(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 Kustom for further information.

shipping_infoArray of objects(shipping_info)[ 0 .. 500 ] items

Shipping information for this capture. Maximum 500 items.

curl -i -X POST \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/captures' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Idempotency-Key: string' \
  -d '{
    "captured_amount": 200000000,
    "description": "string",
    "order_lines": [
      {
        "image_url": "https://yourstore.example/product/headphones.png",
        "merchant_data": "Some metadata",
        "name": "string",
        "product_identifiers": {
          "brand": "Intel",
          "category_path": "Electronics Store > Computers & Tablets > Desktops",
          "color": "Denim blue",
          "global_trade_item_number": "735858293167",
          "manufacturer_part_number": "BOXNUC5CPYH",
          "size": "4"
        },
        "product_url": "https://yourstore.example/product/headphones",
        "quantity": 1,
        "quantity_unit": "pcs.",
        "reference": "75001",
        "subscription": {
          "interval": "MONTH",
          "interval_count": 1,
          "name": "string"
        },
        "tax_rate": 0,
        "total_amount": 200000000,
        "total_discount_amount": 0,
        "total_tax_amount": 200000000,
        "type": "physical",
        "unit_price": 200000000
      }
    ],
    "reference": "string",
    "shipping_delay": 0,
    "shipping_info": [
      {
        "return_shipping_company": "dhl-express",
        "return_tracking_number": "93456415674545679888",
        "return_tracking_uri": "http://shipping.example/findmypackage?93456415674545679888",
        "shipping_company": "dhl-express",
        "shipping_method": "Home",
        "tracking_number": "63456415674545679874",
        "tracking_uri": "http://shipping.example/findmypackage?63456415674545679874"
      }
    ]
  }'

Responses

Capture created

Headers
Capture-Idany

The id of the created capture

Locationany

The URI at which the created capture can be found.

Response
No content

List all order captures

Request

List all order captures

Path
order_idstringrequired

Order id

curl -i -X GET \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/captures'

Responses

Captures found.

Bodyapplication/jsonArray [
billing_addressobject(address)

Shipping address for the capture.

capture_idstring

The capture id. Generated when the capture is created.

Example: "4ba29b50-be7b-44f5-a492-113e6a865e22"
captured_amountinteger(int64)>= 1

The captured amount in minor units.

captured_atstring(date-time)

The time of the capture. Specified in ISO 8601.

Example: "2015-11-19T01:51:17Z"
descriptionstring

Description of the capture shown to the customer.

Example: "Order has been shipped"
klarna_referencestring

Customer friendly reference id, used as a reference when communicating with the customer.

Example: "K4MADNY-1"
order_linesArray of objects(order_line)

List of order lines for the capture shown to the customer.

referencestring[ 0 .. 255 ] characters

Internal reference to the capture which will be included in the settlement files. Max length is 255 characters.

refunded_amountinteger(int64)

Refunded amount for this capture in minor units.

Example: 0
shipping_addressobject(address)

Shipping address for the capture.

shipping_infoArray of objects(shipping_info)

Shipping information for this capture.

]
Response
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": [] } ]

Get capture details

Request

Path
order_idstringrequired

Order id

capture_idstringrequired

Capture id

curl -i -X GET \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/captures/{capture_id}'

Responses

Capture found.

Bodyapplication/json
billing_addressobject(address)

Shipping address for the capture.

capture_idstring

The capture id. Generated when the capture is created.

Example: "4ba29b50-be7b-44f5-a492-113e6a865e22"
captured_amountinteger(int64)>= 1

The captured amount in minor units.

captured_atstring(date-time)

The time of the capture. Specified in ISO 8601.

Example: "2015-11-19T01:51:17Z"
descriptionstring

Description of the capture shown to the customer.

Example: "Order has been shipped"
klarna_referencestring

Customer friendly reference id, used as a reference when communicating with the customer.

Example: "K4MADNY-1"
order_linesArray of objects(order_line)

List of order lines for the capture shown to the customer.

referencestring[ 0 .. 255 ] characters

Internal reference to the capture which will be included in the settlement files. Max length is 255 characters.

refunded_amountinteger(int64)

Refunded amount for this capture in minor units.

Example: 0
shipping_addressobject(address)

Shipping address for the capture.

shipping_infoArray of objects(shipping_info)

Shipping information for this capture.

Response
application/json
{ "billing_address": { "attention": "John Smith", "city": "New York", "country": "US", "email": "test.sam@test.com", "family_name": "Andersson", "given_name": "Adam", "organization_name": "Kustom", "phone": "1-555-555-5555", "postal_code": "10024-3941", "region": "US-NY", "street_address": "509 Amsterdam Ave", "street_address2": "Floor 22 / Flat 2", "title": "Mr." }, "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": { "attention": "John Smith", "city": "New York", "country": "US", "email": "test.sam@test.com", "family_name": "Andersson", "given_name": "Adam", "organization_name": "Kustom", "phone": "1-555-555-5555", "postal_code": "10024-3941", "region": "US-NY", "street_address": "509 Amsterdam Ave", "street_address2": "Floor 22 / Flat 2", "title": "Mr." }, "shipping_info": [ {} ] }

Extend payment due date

Request

Path
order_idstringrequired

Order id

capture_idstringrequired

Capture id

Headers
Klarna-Idempotency-Keystring

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.

Bodyapplication/jsonrequired
number_of_daysinteger(int32)required

Number of days to extend the due date.

curl -i -X PATCH \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/extend-due-date' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Idempotency-Key: string' \
  -d '{
    "number_of_days": 0
  }'

Responses

Due date was extended.

Response
No content

List options for extension of payment due date

Request

Get merchant fees for extension of due date due date

Path
order_idstringrequired

Order id

capture_idstringrequired

Capture id

curl -i -X GET \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/extend-due-date-options'

Responses

Available options found for capture.

Bodyapplication/json
currencystring

The currency for the fees. Specified in ISO 4217 format.

Example: "usd"
optionsArray of objects(OptionDto)

The available options and corresponding fees for extending the due date

Response
application/json
{ "currency": "usd", "options": [ {} ] }

Add shipping information

Request

Path
order_idstringrequired

Order id

capture_idstringrequired

Capture id

Headers
Klarna-Idempotency-Keystring

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.

Bodyapplication/jsonrequired
shipping_infoArray of objects(shipping_info)[ 1 .. 500 ] itemsrequired

New shipping info. Maximum: 500 items.

curl -i -X POST \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/shipping-info' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Idempotency-Key: string' \
  -d '{
    "shipping_info": [
      {
        "return_shipping_company": "dhl-express",
        "return_tracking_number": "93456415674545679888",
        "return_tracking_uri": "http://shipping.example/findmypackage?93456415674545679888",
        "shipping_company": "dhl-express",
        "shipping_method": "Home",
        "tracking_number": "63456415674545679874",
        "tracking_uri": "http://shipping.example/findmypackage?63456415674545679874"
      }
    ]
  }'

Responses

Shipping information was appended.

Response
No content

Send customer communication

Request

Path
order_idstringrequired

Order id

capture_idstringrequired

Capture id

Headers
Klarna-Idempotency-Keystring

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.

curl -i -X POST \
  'https://api.klarna.com/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/trigger-send-out' \
  -H 'Klarna-Idempotency-Key: string'

Responses

Send out was triggered

Response
No content

Refunds

Operations