JSON

Klarna API Reference

Find what you're looking for with our search form.

Introduction

This is the API reference for Klarna's APIs. The checkout API is used to create and update an instance of the Klarna Checkout for the customer to place their order and the order management API is used to handle the order lifecycle.

The APIs are organized around resources using URLs and the different HTTP methods to create and modify these resources. You authenticate using your credentials and basic auth.

API URLs

Klarna APIs are available through different base URLs relating to your location and interaction needs.
To access these APIs, combine the base URL + endpoint, for example to "retrieve an order" construct the URL to call like this
BASE URL for environment + /checkout/v3/orders/ → https://api.klarna.com/checkout/v3/orders/
Use the testing environments to get familiarized with API behaviour and try out things; use the live environments to start real transactions with Klarna.

NOTE: Use HTTPS for all of your interactions with Klarna APIs.

Base URLs - Live (production)

Base URLs - Testing (playground)


Authentication

Example credentials
Username: A100001_1b818918f9db

Password: rPvw912p34CkdLo4

To authenticate with Klarna you use your API Credentials and HTTP Basic auth.

The credentials consist of two elements:

Username - Consists of your Merchant ID (eid) - a unique number that identifies your e-store, combined with a random string.

Password - a string which is associated with your Merchant ID and is used to authorize use of Klarna's APIs

Note: The API credentials are separate from your Merchant ID, and it is possible to have several API credentials associated with the same Merchant ID.

The credentials should be sent as an authorization header for every request with the username and password.

You receive both your live and test credentials by contacting Klarna sales for your country.

If the credentials are missing or wrong Klarna will respond with 401 Unauthorized. You can read more about HTTP Basic auth in the Wikipedia article.

Errors

Example error (multiple errors)
{
  "error_code" : "ERROR_CODE",
  "error_messages" : [
    "This is a human readable english message to aid in debugging",
    "This is another english error message"
  ],
  "correlation_id" : "Unique id for this request used for troubleshooting."
}
Example error (single error)
{
  "error_code" : "ERROR_CODE",
  "error_message" : "This is a single human readable english message to aid in debugging",
  "correlation_id" : "Unique id for this request used for troubleshooting."
}

Klarna's APIs use HTTP status codes together with error objects to handle errors. When an API call fails Klarna will respond with a 4xx or 5xx status code together with a response body containing an error object with the error code, an array of error messages and a unique correlation id to be used to identify the request.

The Error object MUST contain an error_code and an error_messages property (or error_message, see Example).

Location Headers

All Klarna API actions that create a new resource will return a Location header with the precise URL at which the newly created resource can be found. This URL should be used in all interaction with the API regarding this resource. We recommend you to use this URL instead of constructing one yourself.

Metadata

{
  "merchant_data": "The metadata associated with this item."
}

You can store additional metadata with Klarna that will be returned whenever an order is read from Klarna. The data take two forms: two reference fields to be used to store your internal order reference, and general metadata fields on the order and on each order line that can be used to store arbitrary data.

The reference fields are merchant_reference1 and merchant_reference2 used to store the interal reference to the order.

The general metadata fields are merchant_data on the order and merchant_data on each order line.

Data Types

We use a coherent format for currencies, amount and dates across all Klarna APIs.

Currency
{
  "purchase_currency": "usd"
}

We use the ISO 4217 standard for defining currencies. Examples are usd, gbp, eur or sek.

Amount
{
  "order_amount": 1000
}

We express amounts in minor units according to the ISO 4217 standard. That means they are expressed in the smallest unit of currency. Examples are USD with 1000 representing $10, GBP with 500 representing £5, EUR with 50 representing €0.50 and SEK with 100 representing 1kr.

Strings

Strings may be up to 255 characters, unless otherwise noted in the field description.

Dates
{
  "started_at": "2018-08-08T08:37:22Z",
  "date_of_birth": "1981-09-06"
}

Dates are expressed according to the ISO 8601 standard with combined date, time and timezone. The exception to this are date_of_birth fields where we accept values in the YYYY-MM-DD format.

We do not support milliseconds (or any decimal fractions). One example is 2015-08-10T07:45:00Z representing the 10th of August 2015 at 07:45:00 and the UTC timezone.

Locale & Country
{
  "locale": "en-us",
  "purchase_country": "us"
}

Locales should be formatted as a language tag consisting of a two-letter language code combined with a two-letter country code according to RFC 1766. Examples are en-us for US English, en-gb for British English and sv-se for Swedish (in Sweden).

Countries are handled as two-letter country codes according to ISO 3166 alpha-2. Examples are us for the United States, gb for Great Britain and se for Sweden.

Encoding

We expect all data that is sent to Klarna's APIs to be UTF-8 encoded.

Attachment Schema

The Checkout, Payments and Customer Token APIs expect the attachment.body request property to have a string value containing a serialized JSON object, whose structure is reflected by the the following JSON Schema.

API Updates

We always try to update our APIs in a backwards compatible way to avoid breaking existing integrations. Unfortunatly that's not always possible when we iterate on our APIs and release new products and features. Sometimes we need to make breaking changes which will result in a version bump of our APIs. We have collected a list of what we consider to be "non-breaking" changes as well as some integration guidelines.

Non-breaking changes

Guidelines

Checkout API

Download API Specification

The checkout API is used to create a checkout with Klarna and update the checkout order during the purchase.

As soon as the purchase is completed the order should be read and handled using the Order Management API.

Order

Create a new order

Request
Path:POST /checkout/v3/orders
Headers:Content-Type: application/json
See full example
{
    "name": "Women's Fashion",
    "status": "CHECKOUT_INCOMPLETE",
    "locale": "en-US",
    "customer": {
        "type": "person",
        "gender": "male",
        "date_of_birth": "1995-10-20",
        "organization_registration_id": "556737-0431",
        "vat_id": "string"
    },
    "options": {
        "require_validate_callback_success": false,
        "acquiring_channel": "string",
        "vat_removed": false,
        "allow_separate_shipping_address": false,
        "color_button": "#FF9900",
        "color_button_text": "#FF9900",
        "color_checkbox": "#FF9900",
        "color_checkbox_checkmark": "#FF9900",
        "color_header": "#FF9900",
        "color_link": "#FF9900",
        "date_of_birth_mandatory": false,
        "shipping_details": "Delivered within 1-3 working days",
        "title_mandatory": false,
        "additional_checkbox": {
            "text": "Please add me to the newsletter list, read more here \link\",
            "checked": false,
            "required": false
        },
        "national_identification_number_mandatory": false,
        "additional_merchant_terms": "string",
        "phone_mandatory": false,
        "radius_border": "5",
        "allowed_customer_types": [
            "string"
        ],
        "show_subtotal_detail": false,
        "additional_checkboxes": 
            {
                "id": "newsletter_opt_in",
                "text": "Please add me to the newsletter list, read more here \[link\",
                "checked": false,
                "required": false
            }
        ],
        "verify_national_identification_number": false,
        "show_vat_registration_number_field": false
    },
    "attachment": {
        "body": "{\"hotel_reservation_details\": [{\"pnr\": \"VH67899\",\"hotel_intinerary\": [{\"hotel_name\": \"Hotel ltd.\",\"address\": {\"street_address\": \"Storgatan 3\",\"postal_code\": \"113 35\",\"city\": \"Stockholm\",\"country\": \"Sweden\"},\"start_time\": \"2019-01-31T15:00:00Z\",\"end_time\": \"2019-01-31T15:30:00Z\",\"number_of_rooms\": 2,\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@klarna.com\",\"hotel_price\": 23050,\"class\": \"Business\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"air_reservation_details\": [{\"pnr\": \"VH67899\",\"intinerary\": [{\"departure\": \"ARN\",\"departure_city\": \"Stockholm\",\"arrival\": \"NCE\",\"arrival_city\": \"Nice\",\"carrier\": \"SK\",\"segment_price\": 34000,\"departure_date\": \"2019-01-30T15:00:00Z\",\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@klarna.com\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"customer_account_info\": [{\"unique_account_identifier\": \"12345\",\"account_registration_date\": \"2016-01-24T15:00:00Z\",\"account_last_modified\": \"2017-01-24T15:00:00Z\"}],\"payment_history_full\": [{\"payment_option\": \"card\",\"number_paid_purchases\": 2,\"total_amount_paid_purchases\": 1234,\"date_of_last_paid_purchase\": \"2018-01-24T15:00:00Z\",\"date_of_first_paid_purchase\": \"2018-01-24T15:00:00Z\"}]}",
        "content_type": "application/vnd.klarna.internal.emd-v2+json"
    },
    "gui": {
        "options": [
            "string"
        ]
    },
    "recurring": false,
    "tags": [
        "string"
    ],
    "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
    "purchase_country": "US",
    "purchase_currency": "USD",
    "billing_address": {
        "given_name": "John",
        "family_name": "Doe",
        "organization_name": "string",
        "email": "john@doe.com",
        "title": "Mr",
        "street_address": "Lombard St 10",
        "street_address2": "Apt 214",
        "street_name": "Lombard St",
        "street_number": "10",
        "house_extension": "B",
        "postal_code": "90210",
        "city": "Beverly Hills",
        "region": "CA",
        "phone": "333444555",
        "country": "US",
        "care_of": "C/O",
        "reference": "string",
        "attention": "string"
    },
    "shipping_address": {
        "given_name": "John",
        "family_name": "Doe",
        "organization_name": "string",
        "email": "john@doe.com",
        "title": "Mr",
        "street_address": "Lombard St 10",
        "street_address2": "Apt 214",
        "street_name": "Lombard St",
        "street_number": "10",
        "house_extension": "B",
        "postal_code": "90210",
        "city": "Beverly Hills",
        "region": "CA",
        "phone": "333444555",
        "country": "US",
        "care_of": "C/O",
        "reference": "string",
        "attention": "string"
    },
    "order_amount": 50000,
    "order_tax_amount": 4545,
    "order_lines": [
        {
            "type": "physical",
            "reference": "19-402-USA",
            "name": "Red T-Shirt",
            "quantity": 5,
            "quantity_unit": "pcs",
            "unit_price": 10000,
            "tax_rate": 1000,
            "total_amount": 50000,
            "total_discount_amount": 0,
            "total_tax_amount": 4545,
            "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
            "product_url": "https://www.example.com/products/f2a8d7e34",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg",
            "product_identifiers": {
                "brand": "Intel",
                "category_path": "Electronics Store > Computers & Tablets > Desktops",
                "global_trade_item_number": "735858293167",
                "manufacturer_part_number": "BOXNUC5CPYH"
            },
            "shipping_attributes": {
                "weight": 1000,
                "dimensions": {
                    "height": 100,
                    "width": 100,
                    "length": 100
                },
                "tags": [
                    "string"
                ]
            }
        }
    ],
    "merchant_urls": {
        "terms": "https://www.example.com/terms.html",
        "checkout": "https://www.example.com/checkout.html",
        "confirmation": "https://www.example.com/confirmation.html",
        "push": "https://www.example.com/api/push",
        "validation": "https://www.example.com/api/validation",
        "notification": "https://www.example.com/api/pending",
        "cancellation_terms": "https://www.example.com/terms/cancellation.html",
        "shipping_option_update": "https://www.example.com/api/shipment",
        "address_update": "https://www.example.com/api/address",
        "country_change": "https://www.example.com/api/country"
    },
    "html_snippet": "<div id='klarna-checkout-container'><script>alert('Initializing Klarna Checkout');</script></div>",
    "merchant_reference1": "45aa52f387871e3a210645d4",
    "merchant_reference2": "45aa52f387871e3a210645d4",
    "started_at": "2021-09-14T08:54:32.858Z",
    "completed_at": "2021-09-14T08:54:32.858Z",
    "last_modified_at": "2021-09-14T08:54:32.858Z",
    "external_payment_methods": [
        {
            "name": "PayhereUs",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "string"
            ],
            "label": "continue",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg"
        }
    ],
    "external_checkouts": [
        {
            "name": "PayhereUs",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "string"
            ],
            "label": "continue",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg"
        }
    ],
    "shipping_countries": [
        "string"
    ],
    "shipping_options": [
        {
            "id": "express_priority",
            "name": "EXPRESS 1-2 Days",
            "description": "Delivery by 4:30 pm",
            "promo": "Christmas Promotion",
            "price": 0,
            "preselected": false,
            "tax_amount": 0,
            "tax_rate": 0,
            "shipping_method": "PickUpStore",
            "delivery_details": {
                "carrier": "string",
                "class": "string",
                "product": {
                    "name": "string",
                    "identifier": "string"
                },
                "timeslot": {
                    "id": "string",
                    "start": "string",
                    "end": "string"
                },
                "pickup_location": {
                    "id": "string",
                    "name": "string",
                    "address": {
                        "given_name": "John",
                        "family_name": "Doe",
                        "organization_name": "string",
                        "email": "john@doe.com",
                        "title": "Mr",
                        "street_address": "Lombard St 10",
                        "street_address2": "Apt 214",
                        "street_name": "Lombard St",
                        "street_number": "10",
                        "house_extension": "B",
                        "postal_code": "90210",
                        "city": "Beverly Hills",
                        "region": "CA",
                        "phone": "333444555",
                        "country": "US",
                        "care_of": "C/O",
                        "reference": "string",
                        "attention": "string"
                    }
                }
            },
            "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
            "selected_addons": [
                {
                    "type": "string",
                    "price": 0,
                    "external_id": "string",
                    "user_input": "string"
                }
            ]
        }
    ],
    "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
    "merchant_requested": {
        "additional_checkbox": false,
        "additional_checkboxes": [
            {
                "id": "string",
                "checked": false
            }
        ]
    },
    "selected_shipping_option": {
        "id": "express_priority",
        "name": "EXPRESS 1-2 Days",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "preselected": false,
        "tax_amount": 0,
        "tax_rate": 0,
        "shipping_method": "PickUpStore",
        "delivery_details": {
            "carrier": "string",
            "class": "string",
            "product": {
                "name": "string",
                "identifier": "string"
            },
            "timeslot": {
                "id": "string",
                "start": "string",
                "end": "string"
            },
            "pickup_location": {
                "id": "string",
                "name": "string",
                "address": {
                    "given_name": "John",
                    "family_name": "Doe",
                    "organization_name": "string",
                    "email": "john@doe.com",
                    "title": "Mr",
                    "street_address": "Lombard St 10",
                    "street_address2": "Apt 214",
                    "street_name": "Lombard St",
                    "street_number": "10",
                    "house_extension": "B",
                    "postal_code": "90210",
                    "city": "Beverly Hills",
                    "region": "CA",
                    "phone": "333444555",
                    "country": "US",
                    "care_of": "C/O",
                    "reference": "string",
                    "attention": "string"
                }
            }
        },
        "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
        "selected_addons": [
            {
                "type": "string",
                "price": 0,
                "external_id": "string",
                "user_input": "string"
            }
        ]
    },
    "recurring_token": "string",
    "recurring_description": "string",
    "billing_countries": [
        "string"
    ]
}
Response
Description:successful operation
Headers:Status Code: 200
Content-Type: application/json
See full example
{
    "name": "Women's Fashion",
    "status": "CHECKOUT_INCOMPLETE",
    "locale": "en-US",
    "customer": {
        "type": "person",
        "gender": "male",
        "date_of_birth": "1995-10-20",
        "organization_registration_id": "556737-0431",
        "vat_id": "string"
    },
    "options": {
        "require_validate_callback_success": false,
        "acquiring_channel": "string",
        "vat_removed": false,
        "allow_separate_shipping_address": false,
        "color_button": "#FF9900",
        "color_button_text": "#FF9900",
        "color_checkbox": "#FF9900",
        "color_checkbox_checkmark": "#FF9900",
        "color_header": "#FF9900",
        "color_link": "#FF9900",
        "date_of_birth_mandatory": false,
        "shipping_details": "Delivered within 1-3 working days",
        "title_mandatory": false,
        "additional_checkbox": {
            "text": "Please add me to the newsletter list, read more here \link\",
            "checked": false,
            "required": false
        },
        "national_identification_number_mandatory": false,
        "additional_merchant_terms": "string",
        "phone_mandatory": false,
        "radius_border": "5",
        "allowed_customer_types": [
            "string"
        ],
        "show_subtotal_detail": false,
        "additional_checkboxes": 
            {
                "id": "newsletter_opt_in",
                "text": "Please add me to the newsletter list, read more here \[link\",
                "checked": false,
                "required": false
            }
        ],
        "verify_national_identification_number": false,
        "show_vat_registration_number_field": false
    },
    "attachment": {
        "body": "{\"hotel_reservation_details\": [{\"pnr\": \"VH67899\",\"hotel_intinerary\": [{\"hotel_name\": \"Hotel ltd.\",\"address\": {\"street_address\": \"Storgatan 3\",\"postal_code\": \"113 35\",\"city\": \"Stockholm\",\"country\": \"Sweden\"},\"start_time\": \"2019-01-31T15:00:00Z\",\"end_time\": \"2019-01-31T15:30:00Z\",\"number_of_rooms\": 2,\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@klarna.com\",\"hotel_price\": 23050,\"class\": \"Business\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"air_reservation_details\": [{\"pnr\": \"VH67899\",\"intinerary\": [{\"departure\": \"ARN\",\"departure_city\": \"Stockholm\",\"arrival\": \"NCE\",\"arrival_city\": \"Nice\",\"carrier\": \"SK\",\"segment_price\": 34000,\"departure_date\": \"2019-01-30T15:00:00Z\",\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@klarna.com\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"customer_account_info\": [{\"unique_account_identifier\": \"12345\",\"account_registration_date\": \"2016-01-24T15:00:00Z\",\"account_last_modified\": \"2017-01-24T15:00:00Z\"}],\"payment_history_full\": [{\"payment_option\": \"card\",\"number_paid_purchases\": 2,\"total_amount_paid_purchases\": 1234,\"date_of_last_paid_purchase\": \"2018-01-24T15:00:00Z\",\"date_of_first_paid_purchase\": \"2018-01-24T15:00:00Z\"}]}",
        "content_type": "application/vnd.klarna.internal.emd-v2+json"
    },
    "gui": {
        "options": [
            "string"
        ]
    },
    "recurring": false,
    "tags": [
        "string"
    ],
    "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
    "purchase_country": "US",
    "purchase_currency": "USD",
    "billing_address": {
        "given_name": "John",
        "family_name": "Doe",
        "organization_name": "string",
        "email": "john@doe.com",
        "title": "Mr",
        "street_address": "Lombard St 10",
        "street_address2": "Apt 214",
        "street_name": "Lombard St",
        "street_number": "10",
        "house_extension": "B",
        "postal_code": "90210",
        "city": "Beverly Hills",
        "region": "CA",
        "phone": "333444555",
        "country": "US",
        "care_of": "C/O",
        "reference": "string",
        "attention": "string"
    },
    "shipping_address": {
        "given_name": "John",
        "family_name": "Doe",
        "organization_name": "string",
        "email": "john@doe.com",
        "title": "Mr",
        "street_address": "Lombard St 10",
        "street_address2": "Apt 214",
        "street_name": "Lombard St",
        "street_number": "10",
        "house_extension": "B",
        "postal_code": "90210",
        "city": "Beverly Hills",
        "region": "CA",
        "phone": "333444555",
        "country": "US",
        "care_of": "C/O",
        "reference": "string",
        "attention": "string"
    },
    "order_amount": 50000,
    "order_tax_amount": 4545,
    "order_lines": [
        {
            "type": "physical",
            "reference": "19-402-USA",
            "name": "Red T-Shirt",
            "quantity": 5,
            "quantity_unit": "pcs",
            "unit_price": 10000,
            "tax_rate": 1000,
            "total_amount": 50000,
            "total_discount_amount": 0,
            "total_tax_amount": 4545,
            "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
            "product_url": "https://www.example.com/products/f2a8d7e34",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg",
            "product_identifiers": {
                "brand": "Intel",
                "category_path": "Electronics Store > Computers & Tablets > Desktops",
                "global_trade_item_number": "735858293167",
                "manufacturer_part_number": "BOXNUC5CPYH"
            },
            "shipping_attributes": {
                "weight": 1000,
                "dimensions": {
                    "height": 100,
                    "width": 100,
                    "length": 100
                },
                "tags": [
                    "string"
                ]
            }
        }
    ],
    "merchant_urls": {
        "terms": "https://www.example.com/terms.html",
        "checkout": "https://www.example.com/checkout.html",
        "confirmation": "https://www.example.com/confirmation.html",
        "push": "https://www.example.com/api/push",
        "validation": "https://www.example.com/api/validation",
        "notification": "https://www.example.com/api/pending",
        "cancellation_terms": "https://www.example.com/terms/cancellation.html",
        "shipping_option_update": "https://www.example.com/api/shipment",
        "address_update": "https://www.example.com/api/address",
        "country_change": "https://www.example.com/api/country"
    },
    "html_snippet": "<div id='klarna-checkout-container'><script>alert('Initializing Klarna Checkout');</script></div>",
    "merchant_reference1": "45aa52f387871e3a210645d4",
    "merchant_reference2": "45aa52f387871e3a210645d4",
    "started_at": "2021-09-14T08:54:32.858Z",
    "completed_at": "2021-09-14T08:54:32.858Z",
    "last_modified_at": "2021-09-14T08:54:32.858Z",
    "external_payment_methods": [
        {
            "name": "PayhereUs",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "string"
            ],
            "label": "continue",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg"
        }
    ],
    "external_checkouts": [
        {
            "name": "PayhereUs",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "string"
            ],
            "label": "continue",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg"
        }
    ],
    "shipping_countries": [
        "string"
    ],
    "shipping_options": [
        {
            "id": "express_priority",
            "name": "EXPRESS 1-2 Days",
            "description": "Delivery by 4:30 pm",
            "promo": "Christmas Promotion",
            "price": 0,
            "preselected": false,
            "tax_amount": 0,
            "tax_rate": 0,
            "shipping_method": "PickUpStore",
            "delivery_details": {
                "carrier": "string",
                "class": "string",
                "product": {
                    "name": "string",
                    "identifier": "string"
                },
                "timeslot": {
                    "id": "string",
                    "start": "string",
                    "end": "string"
                },
                "pickup_location": {
                    "id": "string",
                    "name": "string",
                    "address": {
                        "given_name": "John",
                        "family_name": "Doe",
                        "organization_name": "string",
                        "email": "john@doe.com",
                        "title": "Mr",
                        "street_address": "Lombard St 10",
                        "street_address2": "Apt 214",
                        "street_name": "Lombard St",
                        "street_number": "10",
                        "house_extension": "B",
                        "postal_code": "90210",
                        "city": "Beverly Hills",
                        "region": "CA",
                        "phone": "333444555",
                        "country": "US",
                        "care_of": "C/O",
                        "reference": "string",
                        "attention": "string"
                    }
                }
            },
            "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
            "selected_addons": [
                {
                    "type": "string",
                    "price": 0,
                    "external_id": "string",
                    "user_input": "string"
                }
            ]
        }
    ],
    "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
    "merchant_requested": {
        "additional_checkbox": false,
        "additional_checkboxes": [
            {
                "id": "string",
                "checked": false
            }
        ]
    },
    "selected_shipping_option": {
        "id": "express_priority",
        "name": "EXPRESS 1-2 Days",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "preselected": false,
        "tax_amount": 0,
        "tax_rate": 0,
        "shipping_method": "PickUpStore",
        "delivery_details": {
            "carrier": "string",
            "class": "string",
            "product": {
                "name": "string",
                "identifier": "string"
            },
            "timeslot": {
                "id": "string",
                "start": "string",
                "end": "string"
            },
            "pickup_location": {
                "id": "string",
                "name": "string",
                "address": {
                    "given_name": "John",
                    "family_name": "Doe",
                    "organization_name": "string",
                    "email": "john@doe.com",
                    "title": "Mr",
                    "street_address": "Lombard St 10",
                    "street_address2": "Apt 214",
                    "street_name": "Lombard St",
                    "street_number": "10",
                    "house_extension": "B",
                    "postal_code": "90210",
                    "city": "Beverly Hills",
                    "region": "CA",
                    "phone": "333444555",
                    "country": "US",
                    "care_of": "C/O",
                    "reference": "string",
                    "attention": "string"
                }
            }
        },
        "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
        "selected_addons": [
            {
                "type": "string",
                "price": 0,
                "external_id": "string",
                "user_input": "string"
            }
        ]
    },
    "recurring_token": "string",
    "recurring_description": "string",
    "billing_countries": [
        "string"
    ]
}
400We were unable to create an order with the provided data. Some field constraint was violated. Show
{
    "error_text": [
        "Bad value: order_amount",
        "Bad value: order_tax_amount",
        "Bad value: locale"
    ]
}
401You were not authorized to execute this operation. Show
{}
Code Examples
Use this API call to create a new order. The response body will contain the full order object and the location header will contain the URL at which the newly created order can be found.

Use this API call to create a new order. The response body will contain the full order object and the location header will contain the URL at which the newly created order can be found.

HTTP Request

POST /checkout/v3/orders

Request parameters Response body

body collapse expand

ParameterDescription
name
string
read only		The merchant name (max 255 characters).
status
string
The current status of the order. The status will be ‘incomplete’ until the customer has been successfully authorized.
locale
string
required		Used to define the language and region of the customer. RFC 1766 customer's locale.
Read more about data types
customer
object

Expand
Customer Object
ParameterDescription
type
string
The default supported value is 'person'. If B2B is enabled for the merchant, the value may be "organization".
gender
string
Customer’s gender - ‘male’ or ‘female’.
date_of_birth
string
Customer’s date of birth. The format is ‘yyyy-mm-dd’. ISO 8601 date.
Read more about data types
organization_registration_id
string
"The organization's official registration id (organization number). Note: Applicable only for B2B orders."
vat_id
string
Organization VAT ID. Only applies for b2b orders.
options
object

Expand
Options Object
ParameterDescription
require_validate_callback_success
boolean
If true, validate callback must get a positive response to not stop purchase. Default: false.
acquiring_channel
string
Acquiring channel for the order. The possible values are:
  • MOTO for "Mail Order Telephone Order"
  • ECOMMERCE for "E-commerce"
  • IN_STORE for "Purchase in boutique"
  • TELESALES for "Telesales/telemarketing"
  • Default : ECOMMERCE
vat_removed
boolean
If true, VAT is not displayed in Checkout's Order Summary page.
allow_separate_shipping_address
boolean
If true, the consumer can enter different billing and shipping addresses. Default: false, except for purchase_country DE where default is: true
color_button
string
Color for the buttons within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_button_text
string
Color for the text inside the buttons within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_checkbox
string
Color for the checkboxes within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_checkbox_checkmark
string
Color for the checkboxes checkmark within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_header
string
Color for the headers within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_link
string
Color for the hyperlinks within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
date_of_birth_mandatory
boolean
If true, the consumer cannot skip date of birth. Default: false
shipping_details
string
A message that will be presented on the confirmation page under the headline "Delivery" (max 255 characters).
title_mandatory
boolean
If specified to false, title becomes optional. Only available for orders for country GB.
additional_checkbox
object

Expand
Checkbox Object
ParameterDescription
text
string
required		Text that will be displayed to the consumer aside the checkbox. Links and formatting can be added using Markdown. (max 1000 characters)
checked
boolean
required		Default state of the additional checkbox. It will use this value when loaded for the first time.
required
boolean
required		Whether it is required for the consumer to check the additional checkbox box or not in order to complete the purchase.
national_identification_number_mandatory
boolean
If true, the user cannot skip national identification number in SE, NO, FI and DK. Default: false. In order to read the national identification number in the validation callback, please contact Klarna’s merchant support.
additional_merchant_terms
string
Additional merchant defined field. e.g. Extra terms and conditions to show. Example: "ADDITIONAL MERCHANT TERMS! [terms link](https://merchant.com/extra_terms)"
phone_mandatory
boolean
If false, the consumer can skip the phone. Only available for orders in DACH countries.
radius_border
string
Radius for the border of elements within the iFrame.
allowed_customer_types
array of strings
A list of allowed customer types. Supported types: person & organization. Example: ["person","organization"]
show_subtotal_detail
boolean
If true, the Order Detail subtotals view is expanded when the Klarna Checkout iFrame is loaded. Default: false
additional_checkboxes
array of checkbox-v2(object)

Expand
Checkbox-v2 Object
ParameterDescription
id
string
required		Identifier used when presenting data back to merchant
text
string
required		Text that will be displayed to the consumer aside the checkbox. Links and formatting can be added using Markdown. (max 1000 characters)
checked
boolean
required		Default state of the additional checkbox. It will use this value when loaded for the first time.
required
boolean
required		Whether it is required for the consumer to check the additional checkbox box or not in order to complete the purchase.
verify_national_identification_number
boolean
Enable verification of National Identification Numbers only in Sweden, Finland and Norway. This option also make the national identification number mandatory. (Not applicable for countries outside of Sweden, Finland and Norway)
show_vat_registration_number_field
boolean
If true, a optional VAT registration number field will be shown in the address form. Only applies for b2b orders.
attachment
object

Expand
Attachment Object
ParameterDescription
body
string
required		The content of the extra merchant data which should be presented as a string inside this property. The body should be an object containing any of the keys and sub objects described below serialised to JSON. More information on that object can be found here.
Expand
ParameterDescription
air_reservation_details
array of air_reservation_details(object)
Details about the reservation of airline tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
IATA Airport Code (three letters)
departure_city
string
arrival
string
IATA Airport Code (three letters)
arrival_city
string
carrier
string
IATA Airline standard (two letters or digits)
segment_price
number
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
bus_reservation_details
array of bus_reservation_details(object)
Details about the reservation of bus tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
City code or name
departure_city
string
arrival
string
City code or name
arrival_city
string
carrier
string
Name of transportation company
segment_price
integer
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
train_reservation_details
array of train_reservation_details(object)
Details about the reservation of train tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
City code or name
departure_city
string
arrival
string
City code or name
arrival_city
string
carrier
string
Name of transportation company
segment_price
integer
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
ferry_reservation_details
array of ferry_reservation_details(object)
Details about the reservation of ferry tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
City code or name
departure_city
string
arrival
string
City code or name
arrival_city
string
carrier
string
Name of transportation company
segment_price
integer
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
hotel_reservation_details
array of hotel_reservation_details(object)
Details about the reservation of hotel rooms
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
hotel_itinerary
array of hotel_itinerary(object)
Hotel itinerary data, one per hotel stay
Expand
ParameterDescription
hotel_name
string
Name of hotel
address
object

Expand
Address Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
number_of_rooms
integer
passenger_id
array of passenger_id(integer)
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
hotel_price
number
Local currency
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
car_rental_reservation_details
array of car_rental_reservation_details(object)
Details about the reservation of rental cars
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
car_rental_itinerary
array of car_rental_itinerary(object)
Car rental itinerary data
Expand
ParameterDescription
rental_company
string
Name of rental company
drivers_id
array of drivers_id(integer)
pick_up_location
object

Expand
Pick Up Location Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
drop_off_location
object

Expand
Drop Off Location Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
car_price
number
Local currency
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
drivers
array of drivers(object)

Expand
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
event
array of event(object)

Expand
ParameterDescription
event_name
string
Name of the event, e.g. "Fancy Singer"
event_company
string
Name of the company arranging the event, e.g. "Happy Parties Ltd."
genre_of_event
string
Category or type of venue, "Pop"
arena_name
string
Name of the venue, "Song Arena"
arena_location
object
Location of the arena.
Expand
Location Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
access_controlled_venue
boolean
Tickets are digitally checked when enetering the venue
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
voucher
array of voucher(object)

Expand
ParameterDescription
voucher_name
string
Description of the product the voucher entitles to, e.g. "China trip"
voucher_company
string
Name of the company that will provide good / service upon voucher (not the same as the selling merchant), e.g. "Sun Trips Ltd."
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
subscription
array of subscription(object)

Expand
ParameterDescription
subscription_name
string
Name of the product on subscription, e.g. "Contact lenses"
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
auto_renewal_of_subscription
boolean
Info whether the subscription will be auto renewed upon expiry.
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
marketplace_seller_info
array of marketplace_seller_info(object)

Expand
ParameterDescription
unique_account_identifier_seller
object

Expand
Unique Account Identifier Seller Object
ParameterDescription
email
string
pno
string
other
string
sub_merchant_id
string
Name or unique number of the selling / delivering merchant, e.g. "Marketbrick Ltd."
product_category
string
Name of the overall category to which the specific good(s) belong to, according to the selling merchants categorization. E.g. "Computers"
product_name
string
Name of the specific good purchased, e.g. "Acer 5400"
account_registration_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
account_last_modified
object

Expand
Account Last Modified Object
ParameterDescription
password
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
email
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
listing
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
login
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
address
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
seller_rating
number
Current rating. Partner should provide upfront their rating scale, e.g. 65
number_of_trades
integer
Number of trades the sub-merchant did since 12 months back, e.g. 23
volume_of_trades
integer
Volumes of trades the sub-merchant did since 12 months back, e.g. 230.5
marketplace_winner_info
array of marketplace_winner_info(object)

Expand
ParameterDescription
unique_account_identifier_winner
object

Expand
Unique Account Identifier Winner Object
ParameterDescription
email
string
pno
string
other
string
account_registration_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
account_last_modified
object

Expand
Account Last Modified Object
ParameterDescription
password
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
email
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
listing
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
login
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
address
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
number_of_trades
integer
Number of trades the winner did since 12 months back, e.g. 5
volume_of_trades
integer
Volume of trades the winner did since 12 months back, 230.5
customer_account_info
array of customer_account_info(object)

Expand
ParameterDescription
unique_account_identifier
string
Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
account_registration_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
account_last_modified
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
payment_history_full
array of payment_history_full(object)

Expand
ParameterDescription
unique_account_identifier
string
Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
payment_option
string
  • card
  • direct banking
  • non klarna credit
  • sms
  • other
number_paid_purchases
integer
Total number of successful purchases
total_amount_paid_purchases
number
Total amount of successful purchases (local currency), e.g. 1234.00
date_of_last_paid_purchase
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
date_of_first_paid_purchase
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
payment_history_simple
array of payment_history_simple(object)

Expand
ParameterDescription
unique_account_identifier
string
Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
paid_before
boolean
Whether the customer has paid before or not
other_delivery_address
array of other_delivery_address(object)

Expand
ParameterDescription
shipping_method
undefined
  • store pick-up
  • pick-up point
  • registered box
  • unregistered box
shipping_type
undefined
  • normal
  • express
first_name
string
last_name
string
street_address
string
street_number
string
postal_code
string
city
string
country
string
content_type
string
required		The content type of the body. It is usually represented as "application/vnd.klarna.internal.emd-v2+json"
gui
object

Expand
Gui Object
ParameterDescription
options
array of strings
An array of options to define the checkout behaviour. Supported options: minimal_confirmation. The gui object is an array of options to modify checkout client ui behaviours. Examples: ["minimal_confirmation"]
recurring
boolean
Indicates whether this purchase will create a token that can be used by the merchant to create recurring purchases. This must be enabled for the merchant to use. Default: false Depending on specified country, recurring could be used for the following payment methods: Pay Later, Direct Debit, Card.
tags
array of strings
Extra information added to the order. Example: ["dangerous_goods", "bulky"]
order_id
string
read only		Unique order ID that will be used for the entire lifecycle of the order. (max 255 characters)
purchase_country
string
required		The purchase country of the merchant's store. The format to be used is ISO 3166 alpha-2. Eg: GB, SE, DE, US, etc. Note: purchase country and currency need to match the defined merchant configuration. For global configuration read this https://developers.klarna.com/documentation/klarna-checkout/kco-global/
Read more about data types
purchase_currency
string
required		The purchase currency of the merchant's store. The format to be used is ISO 4217. Eg: USD, EUR, SEK, GBP, etc. Note: purchase country and currency need to match the defined merchant configuration. For global configuration read this https://developers.klarna.com/documentation/klarna-checkout/kco-global/
Read more about data types
billing_address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
shipping_address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
order_amount
integer
required		Total amount of the order including tax and any available discounts. The value should be in non-negative minor units. Example: 25 Euros should be 2500.
order_tax_amount
integer
required		Total tax amount of the order. The value should be in non-negative minor units. Example: 25 Euros should be 2500.
order_lines
array of order_line(object)
required		An array containing list of line items that are part of this order. Maximum of 1000 line items could be processed in a single order.
Expand
Order Line Object
ParameterDescription
type
string
Type of the order line item. The possible values are:
  • physical (physical good)
  • discount
  • shipping_fee
  • sales_tax (depends on the country/city, usually called VAT)
  • digital (digital good)
  • gift_card
  • store_credit (credit from the merchant)
  • surcharge (extra charge)
reference
string
Article number, SKU or similar. (max 64 characters)
name
string
required		Descriptive name of the order line item (max 255 characters)
quantity
integer
required		Non-negative number. Quantity of the order line item.
quantity_unit
string
Unit used to describe the quantity, e.g. kg, pcs... If defined has to be 1-8 characters
unit_price
integer
required		Minor units. Includes tax, excludes discount. (max value: 100000000). Example: 100 Euros should be 10000.
tax_rate
integer
required		Non-negative value. The percentage value is represented with two implicit decimals. (max 10000) Example: 25% should be 2500.
total_amount
integer
required		Minor units. Includes tax and discount. Example: 25 euros should be 2500 Value = (quantity x unit_price) - total_discount_amount. (max value: 100000000)
total_discount_amount
integer
Non-negative minor units. Includes tax. Example: 25 euros should be 2500
total_tax_amount
integer
required		Must be within ±1 of total_amount - total_amount * 10000 / (10000 + tax_rate). Negative when type is discount.
merchant_data
string
Property used to store additional metadata per item that will be returned whenever an order is read from Klarna. Pass through field. (max 1024 characters).
product_url
string
URL to the product page that can be later embedded in communications between Klarna and the customer. (max 1024 characters)
image_url
string
URL to an image that can be later embedded in communications between Klarna and the customer. (max 1024 characters) Improves post-purchase customer experiences.
product_identifiers
object

Expand
Product Identifiers Object
ParameterDescription
brand
string
The product's brand name as generally recognized by consumers. If no brand is available for a product, do not supply any value.
category_path
string
The product's category path as used in the merchant's webshop. Include the full and most detailed category and separate the segments with ' > '. (max 750 characters) Example: "Electronics Store > Computers & Tablets > Desktops"
global_trade_item_number
string
The product's Global Trade Item Number (GTIN). Common types of GTIN are EAN, ISBN or UPC. Exclude dashes and spaces, where possible
manufacturer_part_number
string
The product's Manufacturer Part Number (MPN), which - together with the brand - uniquely identifies a product. Only submit MPNs assigned by a manufacturer and use the most specific MPN possible
shipping_attributes
object

Expand
Shipping Attributes Object
ParameterDescription
weight
integer
The product's weight as used in the merchant's webshop. Non-negative. Measured in grams.
dimensions
object

Expand
Dimensions Object
ParameterDescription
height
integer
The product's height as used in the merchant's webshop. Non-negative. Measured in millimeters.
width
integer
The product's width as used in the merchant's webshop. Non-negative. Measured in millimeters.
length
integer
The product's length as used in the merchant's webshop. Non-negative. Measured in millimeters.
tags
array of strings
The product's extra features, example ["dangerous_goods", "bulky"]
merchant_urls
object

Expand
Merchant Urls Object
ParameterDescription
terms
string
required		URL for the terms and conditions page of the merchant. The URL will be displayed inside the Klarna Checkout iFrame.(max 2000 characters) Example: "https://merchant.com/terms"
checkout
string
required		URL for the checkout page of the merchant. (max 2000 characters) Example: "https://merchant.com/checkout"
confirmation
string
required		URL of the merchant confirmation page. The consumer will be redirected back to the confirmation page if the authorization is successful after the customer clicks on the ‘Place Order’ button inside checkout. The special characters of the confirmation URL should be encoded, e.g. the "space" character should be written as "%20". Then, on top of that, the whole confirmation URL should be encoded. E.g. the "space" character should become "%2520". (max 2000 characters) Example: "https://merchant.com/confirmation"
push
string
required		URL that will be used for push notification when an order is completed. Should be different than checkout and confirmation URLs. (max 2000 characters) Example: "https://merchant.com/push"
validation
string
URL that will be requested for final merchant validation. (must be https, max 2000 characters) Example: "https://merchant.com/validation"
notification
string
URL for notifications on pending orders. (max 2000 characters) Example: "https://merchant.com/notification/{checkout.order.id}"
cancellation_terms
string
URL for the cancellation terms page of the merchant. The URL will be displayed in the email that is sent to the customer after the order is captured.(max 2000 characters) Example: "https://merchant.com/terms/cancelation"
shipping_option_update
string
URL for shipping option update. (must be https, max 2000 characters) Example: "https://merchant.com/shippingoptionupdate"
address_update
string
URL for shipping, tax and purchase currency updates. Will be called on address changes. (must be https, max 2000 characters) Example: "https://merchant.com/addressupdate"
country_change
string
URL for shipping, tax and purchase currency updates. Will be called on billing or shipping country changes. (must be https, max 2000 characters) Example: "https://merchant.com/countrychange"
html_snippet
string
read only		The HTML snippet that is used to render the checkout in an iframe.
merchant_reference1
string
Used for storing merchant's internal order number or other reference. If set, will be shown on the confirmation page as "order number" . The value is also available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"
merchant_reference2
string
Used for storing merchant's internal order number or other reference. The value is available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"
started_at
string (datetime)
read only		ISO 8601 datetime. The date and time when the order has been created. The format will be as follows: "yyyy-mm-ddThh:mm:ssZ"
Read more about data types
completed_at
string (datetime)
read only		ISO 8601 datetime. The date and time when the order has been completed. The format will be as follows: "yyyy-mm-ddThh:mm:ssZ"
Read more about data types
last_modified_at
string (datetime)
read only		ISO 8601 datetime. The date and time when the order was last modified. The format will be as follows: "yyyy-mm-ddThh:mm:ssZ"
Read more about data types
external_payment_methods
array of payment_provider(object)
List of external payment methods that will be displayed as part of payment methods in the checkout.
Expand
Payment Provider Object
ParameterDescription
name
string
required		The name of the payment provider. (max 255 characters)
fee
integer
Minor units. Includes tax.
description
string
Description. (max 500 characters)
countries
array of strings
If specified, limits the method to the listed countries (alpha 2 codes).
label
string
Controls label of buy button
  • continue
  • complete
redirect_url
string
required		URL to redirect to. (must be https, min 7, max 2000 characters)
image_url
string
URL to an image to display. (must be https, max 2000 characters)
external_checkouts
array of payment_provider(object)
List of external checkouts that will be displayed as part of payment methods in the checkout. The image_url is required, and the image size has to be 276x48px
Expand
Payment Provider Object
ParameterDescription
name
string
required		The name of the payment provider. (max 255 characters)
fee
integer
Minor units. Includes tax.
description
string
Description. (max 500 characters)
countries
array of strings
If specified, limits the method to the listed countries (alpha 2 codes).
label
string
Controls label of buy button
  • continue
  • complete
redirect_url
string
required		URL to redirect to. (must be https, min 7, max 2000 characters)
image_url
string
URL to an image to display. (must be https, max 2000 characters)
shipping_countries
array of strings
List of allowed shipping countries for this order in ISO-3166 alpha-2 format. If specified, the customer will be able to change the shipping country in the checkout and you will be notified through ‘address_update’ callback or the ‘shipping_address_change’ javascript event. If not specified then the default value will be the purchase country. Example: look at billing_countries example.
shipping_options
array of shipping_option(object)
A list of shipping options available for this order.
Expand
Shipping Option Object
ParameterDescription
id
string
required		id
name
string
required		Name.
description
string
Description.
promo
string
Promotion name. To be used if this shipping option is promotional.
price
integer
required		Price including tax.
preselected
boolean
If true, this option will be preselected when checkout loads. Default: false
tax_amount
integer
required		Tax amount.
tax_rate
integer
required		Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
shipping_method
string
Shipping method. Possible values:
  • PickUpStore
  • Home
  • BoxReg
  • BoxUnreg
  • PickUpPoint
  • Own
  • Postal
  • DHLPackstation
  • Digital
If DHLPackstation is selected the correct form will be displayed.
delivery_details
object

Expand
DeliveryDetailsV1 Object
ParameterDescription
carrier
string
Carrier product name
class
string
Type of shipping class
product
object

Expand
ProductV1 Object
ParameterDescription
name
string
Carrier product name
identifier
string
Carrier product identifier
timeslot
object

Expand
TimeslotV1 Object
ParameterDescription
id
string
Id
start
string
Start time
end
string
End time
pickup_location
object

Expand
PickupLocationV1 Object
ParameterDescription
id
string
Id
name
string
Name of the location
address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
tms_reference
string
TMS reference. Required to map completed orders to shipments reserved in TMS.
selected_addons
array of selected_addon(object)

Expand
Selected Addon Object
ParameterDescription
type
string
price
integer
external_id
string
user_input
string
merchant_data
string
Pass through field to send any information about the order to be used later for reference while retrieving the order details (max 6000 characters).
merchant_requested
object

Expand
Merchant Requested Object
ParameterDescription
additional_checkbox
boolean
read only		Informs whether the additional_checkbox is checked or not, when applicable.
additional_checkboxes
array of merchant_requested_checkbox(object)
read only		Informs whether the additional_checkboxes is checked or not, when applicable.
Expand
Merchant Requested Checkbox Object
ParameterDescription
id
string
checked
boolean
selected_shipping_option
object

Expand
Shipping Option Object
ParameterDescription
id
string
required		id
name
string
required		Name.
description
string
Description.
promo
string
Promotion name. To be used if this shipping option is promotional.
price
integer
required		Price including tax.
preselected
boolean
If true, this option will be preselected when checkout loads. Default: false
tax_amount
integer
required		Tax amount.
tax_rate
integer
required		Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
shipping_method
string
Shipping method. Possible values:
  • PickUpStore
  • Home
  • BoxReg
  • BoxUnreg
  • PickUpPoint
  • Own
  • Postal
  • DHLPackstation
  • Digital
If DHLPackstation is selected the correct form will be displayed.
delivery_details
object

Expand
DeliveryDetailsV1 Object
ParameterDescription
carrier
string
Carrier product name
class
string
Type of shipping class
product
object

Expand
ProductV1 Object
ParameterDescription
name
string
Carrier product name
identifier
string
Carrier product identifier
timeslot
object

Expand
TimeslotV1 Object
ParameterDescription
id
string
Id
start
string
Start time
end
string
End time
pickup_location
object

Expand
PickupLocationV1 Object
ParameterDescription
id
string
Id
name
string
Name of the location
address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
tms_reference
string
TMS reference. Required to map completed orders to shipments reserved in TMS.
selected_addons
array of selected_addon(object)

Expand
Selected Addon Object
ParameterDescription
type
string
price
integer
external_id
string
user_input
string
recurring_token
string
read only		Token to be used when creating recurring orders.
recurring_description
string
read only		Description to be added to the recurring order.
billing_countries
array of strings
List of allowed billing countries for this order. If specified, the customer will be able to change the billing country in the checkout and you will be notified through ‘country_change’ callback or the ‘billing_address_change’ javascript event. If not specified but shipping_countries is specified, will use same values as shipping_countries. If not specified and shipping_countries is not specified, then the default value will be the purchase country. Example: ["AD", "AE", "AG", "AI", "AL", "AM", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CF", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GR", "GS", "GT", "GU", "GY", "HK", "HN", "HR", "HU", "ID", "IE", "IL", "IM", "IN", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SR", "ST", "SV", "SX", "SZ", "TC", "TF", "TG", "TH", "TJ", "TK", "TL", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YT", "ZA", "ZM", "ZW"]"
ParameterDescription
name
string
read only		The merchant name (max 255 characters).
status
string
The current status of the order. The status will be ‘incomplete’ until the customer has been successfully authorized.
locale
string
required		Used to define the language and region of the customer. RFC 1766 customer's locale.
Read more about data types
customer
object

Expand
Customer Object
ParameterDescription
type
string
The default supported value is 'person'. If B2B is enabled for the merchant, the value may be "organization".
gender
string
Customer’s gender - ‘male’ or ‘female’.
date_of_birth
string
Customer’s date of birth. The format is ‘yyyy-mm-dd’. ISO 8601 date.
Read more about data types
organization_registration_id
string
"The organization's official registration id (organization number). Note: Applicable only for B2B orders."
vat_id
string
Organization VAT ID. Only applies for b2b orders.
options
object

Expand
Options Object
ParameterDescription
require_validate_callback_success
boolean
If true, validate callback must get a positive response to not stop purchase. Default: false.
acquiring_channel
string
Acquiring channel for the order. The possible values are:
  • MOTO for "Mail Order Telephone Order"
  • ECOMMERCE for "E-commerce"
  • IN_STORE for "Purchase in boutique"
  • TELESALES for "Telesales/telemarketing"
  • Default : ECOMMERCE
vat_removed
boolean
If true, VAT is not displayed in Checkout's Order Summary page.
allow_separate_shipping_address
boolean
If true, the consumer can enter different billing and shipping addresses. Default: false, except for purchase_country DE where default is: true
color_button
string
Color for the buttons within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_button_text
string
Color for the text inside the buttons within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_checkbox
string
Color for the checkboxes within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_checkbox_checkmark
string
Color for the checkboxes checkmark within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_header
string
Color for the headers within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_link
string
Color for the hyperlinks within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
date_of_birth_mandatory
boolean
If true, the consumer cannot skip date of birth. Default: false
shipping_details
string
A message that will be presented on the confirmation page under the headline "Delivery" (max 255 characters).
title_mandatory
boolean
If specified to false, title becomes optional. Only available for orders for country GB.
additional_checkbox
object

Expand
Checkbox Object
ParameterDescription
text
string
required		Text that will be displayed to the consumer aside the checkbox. Links and formatting can be added using Markdown. (max 1000 characters)
checked
boolean
required		Default state of the additional checkbox. It will use this value when loaded for the first time.
required
boolean
required		Whether it is required for the consumer to check the additional checkbox box or not in order to complete the purchase.
national_identification_number_mandatory
boolean
If true, the user cannot skip national identification number in SE, NO, FI and DK. Default: false. In order to read the national identification number in the validation callback, please contact Klarna’s merchant support.
additional_merchant_terms
string
Additional merchant defined field. e.g. Extra terms and conditions to show. Example: "ADDITIONAL MERCHANT TERMS! [terms link](https://merchant.com/extra_terms)"
phone_mandatory
boolean
If false, the consumer can skip the phone. Only available for orders in DACH countries.
radius_border
string
Radius for the border of elements within the iFrame.
allowed_customer_types
array of strings
A list of allowed customer types. Supported types: person & organization. Example: ["person","organization"]
show_subtotal_detail
boolean
If true, the Order Detail subtotals view is expanded when the Klarna Checkout iFrame is loaded. Default: false
additional_checkboxes
array of checkbox-v2(object)

Expand
Checkbox-v2 Object
ParameterDescription
id
string
required		Identifier used when presenting data back to merchant
text
string
required		Text that will be displayed to the consumer aside the checkbox. Links and formatting can be added using Markdown. (max 1000 characters)
checked
boolean
required		Default state of the additional checkbox. It will use this value when loaded for the first time.
required
boolean
required		Whether it is required for the consumer to check the additional checkbox box or not in order to complete the purchase.
verify_national_identification_number
boolean
Enable verification of National Identification Numbers only in Sweden, Finland and Norway. This option also make the national identification number mandatory. (Not applicable for countries outside of Sweden, Finland and Norway)
show_vat_registration_number_field
boolean
If true, a optional VAT registration number field will be shown in the address form. Only applies for b2b orders.
attachment
object

Expand
Attachment Object
ParameterDescription
body
string
required		The content of the extra merchant data which should be presented as a string inside this property. The body should be an object containing any of the keys and sub objects described below serialised to JSON. More information on that object can be found here.
Expand
ParameterDescription
air_reservation_details
array of air_reservation_details(object)
Details about the reservation of airline tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
IATA Airport Code (three letters)
departure_city
string
arrival
string
IATA Airport Code (three letters)
arrival_city
string
carrier
string
IATA Airline standard (two letters or digits)
segment_price
number
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
bus_reservation_details
array of bus_reservation_details(object)
Details about the reservation of bus tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
City code or name
departure_city
string
arrival
string
City code or name
arrival_city
string
carrier
string
Name of transportation company
segment_price
integer
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
train_reservation_details
array of train_reservation_details(object)
Details about the reservation of train tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
City code or name
departure_city
string
arrival
string
City code or name
arrival_city
string
carrier
string
Name of transportation company
segment_price
integer
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
ferry_reservation_details
array of ferry_reservation_details(object)
Details about the reservation of ferry tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
City code or name
departure_city
string
arrival
string
City code or name
arrival_city
string
carrier
string
Name of transportation company
segment_price
integer
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
hotel_reservation_details
array of hotel_reservation_details(object)
Details about the reservation of hotel rooms
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
hotel_itinerary
array of hotel_itinerary(object)
Hotel itinerary data, one per hotel stay
Expand
ParameterDescription
hotel_name
string
Name of hotel
address
object

Expand
Address Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
number_of_rooms
integer
passenger_id
array of passenger_id(integer)
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
hotel_price
number
Local currency
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
car_rental_reservation_details
array of car_rental_reservation_details(object)
Details about the reservation of rental cars
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
car_rental_itinerary
array of car_rental_itinerary(object)
Car rental itinerary data
Expand
ParameterDescription
rental_company
string
Name of rental company
drivers_id
array of drivers_id(integer)
pick_up_location
object

Expand
Pick Up Location Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
drop_off_location
object

Expand
Drop Off Location Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
car_price
number
Local currency
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
drivers
array of drivers(object)

Expand
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
event
array of event(object)

Expand
ParameterDescription
event_name
string
Name of the event, e.g. "Fancy Singer"
event_company
string
Name of the company arranging the event, e.g. "Happy Parties Ltd."
genre_of_event
string
Category or type of venue, "Pop"
arena_name
string
Name of the venue, "Song Arena"
arena_location
object
Location of the arena.
Expand
Location Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
access_controlled_venue
boolean
Tickets are digitally checked when enetering the venue
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
voucher
array of voucher(object)

Expand
ParameterDescription
voucher_name
string
Description of the product the voucher entitles to, e.g. "China trip"
voucher_company
string
Name of the company that will provide good / service upon voucher (not the same as the selling merchant), e.g. "Sun Trips Ltd."
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
subscription
array of subscription(object)

Expand
ParameterDescription
subscription_name
string
Name of the product on subscription, e.g. "Contact lenses"
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
auto_renewal_of_subscription
boolean
Info whether the subscription will be auto renewed upon expiry.
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
marketplace_seller_info
array of marketplace_seller_info(object)

Expand
ParameterDescription
unique_account_identifier_seller
object

Expand
Unique Account Identifier Seller Object
ParameterDescription
email
string
pno
string
other
string
sub_merchant_id
string
Name or unique number of the selling / delivering merchant, e.g. "Marketbrick Ltd."
product_category
string
Name of the overall category to which the specific good(s) belong to, according to the selling merchants categorization. E.g. "Computers"
product_name
string
Name of the specific good purchased, e.g. "Acer 5400"
account_registration_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
account_last_modified
object

Expand
Account Last Modified Object
ParameterDescription
password
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
email
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
listing
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
login
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
address
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
seller_rating
number
Current rating. Partner should provide upfront their rating scale, e.g. 65
number_of_trades
integer
Number of trades the sub-merchant did since 12 months back, e.g. 23
volume_of_trades
integer
Volumes of trades the sub-merchant did since 12 months back, e.g. 230.5
marketplace_winner_info
array of marketplace_winner_info(object)

Expand
ParameterDescription
unique_account_identifier_winner
object

Expand
Unique Account Identifier Winner Object
ParameterDescription
email
string
pno
string
other
string
account_registration_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
account_last_modified
object

Expand
Account Last Modified Object
ParameterDescription
password
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
email
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
listing
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
login
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
address
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
number_of_trades
integer
Number of trades the winner did since 12 months back, e.g. 5
volume_of_trades
integer
Volume of trades the winner did since 12 months back, 230.5
customer_account_info
array of customer_account_info(object)

Expand
ParameterDescription
unique_account_identifier
string
Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
account_registration_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
account_last_modified
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
payment_history_full
array of payment_history_full(object)

Expand
ParameterDescription
unique_account_identifier
string
Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
payment_option
string
  • card
  • direct banking
  • non klarna credit
  • sms
  • other
number_paid_purchases
integer
Total number of successful purchases
total_amount_paid_purchases
number
Total amount of successful purchases (local currency), e.g. 1234.00
date_of_last_paid_purchase
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
date_of_first_paid_purchase
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
payment_history_simple
array of payment_history_simple(object)

Expand
ParameterDescription
unique_account_identifier
string
Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
paid_before
boolean
Whether the customer has paid before or not
other_delivery_address
array of other_delivery_address(object)

Expand
ParameterDescription
shipping_method
undefined
  • store pick-up
  • pick-up point
  • registered box
  • unregistered box
shipping_type
undefined
  • normal
  • express
first_name
string
last_name
string
street_address
string
street_number
string
postal_code
string
city
string
country
string
content_type
string
required		The content type of the body. It is usually represented as "application/vnd.klarna.internal.emd-v2+json"
gui
object

Expand
Gui Object
ParameterDescription
options
array of strings
An array of options to define the checkout behaviour. Supported options: minimal_confirmation. The gui object is an array of options to modify checkout client ui behaviours. Examples: ["minimal_confirmation"]
recurring
boolean
Indicates whether this purchase will create a token that can be used by the merchant to create recurring purchases. This must be enabled for the merchant to use. Default: false Depending on specified country, recurring could be used for the following payment methods: Pay Later, Direct Debit, Card.
tags
array of strings
Extra information added to the order. Example: ["dangerous_goods", "bulky"]
order_id
string
read only		Unique order ID that will be used for the entire lifecycle of the order. (max 255 characters)
purchase_country
string
required		The purchase country of the merchant's store. The format to be used is ISO 3166 alpha-2. Eg: GB, SE, DE, US, etc. Note: purchase country and currency need to match the defined merchant configuration. For global configuration read this https://developers.klarna.com/documentation/klarna-checkout/kco-global/
Read more about data types
purchase_currency
string
required		The purchase currency of the merchant's store. The format to be used is ISO 4217. Eg: USD, EUR, SEK, GBP, etc. Note: purchase country and currency need to match the defined merchant configuration. For global configuration read this https://developers.klarna.com/documentation/klarna-checkout/kco-global/
Read more about data types
billing_address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
shipping_address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
order_amount
integer
required		Total amount of the order including tax and any available discounts. The value should be in non-negative minor units. Example: 25 Euros should be 2500.
order_tax_amount
integer
required		Total tax amount of the order. The value should be in non-negative minor units. Example: 25 Euros should be 2500.
order_lines
array of order_line(object)
required		An array containing list of line items that are part of this order. Maximum of 1000 line items could be processed in a single order.
Expand
Order Line Object
ParameterDescription
type
string
Type of the order line item. The possible values are:
  • physical (physical good)
  • discount
  • shipping_fee
  • sales_tax (depends on the country/city, usually called VAT)
  • digital (digital good)
  • gift_card
  • store_credit (credit from the merchant)
  • surcharge (extra charge)
reference
string
Article number, SKU or similar. (max 64 characters)
name
string
required		Descriptive name of the order line item (max 255 characters)
quantity
integer
required		Non-negative number. Quantity of the order line item.
quantity_unit
string
Unit used to describe the quantity, e.g. kg, pcs... If defined has to be 1-8 characters
unit_price
integer
required		Minor units. Includes tax, excludes discount. (max value: 100000000). Example: 100 Euros should be 10000.
tax_rate
integer
required		Non-negative value. The percentage value is represented with two implicit decimals. (max 10000) Example: 25% should be 2500.
total_amount
integer
required		Minor units. Includes tax and discount. Example: 25 euros should be 2500 Value = (quantity x unit_price) - total_discount_amount. (max value: 100000000)
total_discount_amount
integer
Non-negative minor units. Includes tax. Example: 25 euros should be 2500
total_tax_amount
integer
required		Must be within ±1 of total_amount - total_amount * 10000 / (10000 + tax_rate). Negative when type is discount.
merchant_data
string
Property used to store additional metadata per item that will be returned whenever an order is read from Klarna. Pass through field. (max 1024 characters).
product_url
string
URL to the product page that can be later embedded in communications between Klarna and the customer. (max 1024 characters)
image_url
string
URL to an image that can be later embedded in communications between Klarna and the customer. (max 1024 characters) Improves post-purchase customer experiences.
product_identifiers
object

Expand
Product Identifiers Object
ParameterDescription
brand
string
The product's brand name as generally recognized by consumers. If no brand is available for a product, do not supply any value.
category_path
string
The product's category path as used in the merchant's webshop. Include the full and most detailed category and separate the segments with ' > '. (max 750 characters) Example: "Electronics Store > Computers & Tablets > Desktops"
global_trade_item_number
string
The product's Global Trade Item Number (GTIN). Common types of GTIN are EAN, ISBN or UPC. Exclude dashes and spaces, where possible
manufacturer_part_number
string
The product's Manufacturer Part Number (MPN), which - together with the brand - uniquely identifies a product. Only submit MPNs assigned by a manufacturer and use the most specific MPN possible
shipping_attributes
object

Expand
Shipping Attributes Object
ParameterDescription
weight
integer
The product's weight as used in the merchant's webshop. Non-negative. Measured in grams.
dimensions
object

Expand
Dimensions Object
ParameterDescription
height
integer
The product's height as used in the merchant's webshop. Non-negative. Measured in millimeters.
width
integer
The product's width as used in the merchant's webshop. Non-negative. Measured in millimeters.
length
integer
The product's length as used in the merchant's webshop. Non-negative. Measured in millimeters.
tags
array of strings
The product's extra features, example ["dangerous_goods", "bulky"]
merchant_urls
object

Expand
Merchant Urls Object
ParameterDescription
terms
string
required		URL for the terms and conditions page of the merchant. The URL will be displayed inside the Klarna Checkout iFrame.(max 2000 characters) Example: "https://merchant.com/terms"
checkout
string
required		URL for the checkout page of the merchant. (max 2000 characters) Example: "https://merchant.com/checkout"
confirmation
string
required		URL of the merchant confirmation page. The consumer will be redirected back to the confirmation page if the authorization is successful after the customer clicks on the ‘Place Order’ button inside checkout. The special characters of the confirmation URL should be encoded, e.g. the "space" character should be written as "%20". Then, on top of that, the whole confirmation URL should be encoded. E.g. the "space" character should become "%2520". (max 2000 characters) Example: "https://merchant.com/confirmation"
push
string
required		URL that will be used for push notification when an order is completed. Should be different than checkout and confirmation URLs. (max 2000 characters) Example: "https://merchant.com/push"
validation
string
URL that will be requested for final merchant validation. (must be https, max 2000 characters) Example: "https://merchant.com/validation"
notification
string
URL for notifications on pending orders. (max 2000 characters) Example: "https://merchant.com/notification/{checkout.order.id}"
cancellation_terms
string
URL for the cancellation terms page of the merchant. The URL will be displayed in the email that is sent to the customer after the order is captured.(max 2000 characters) Example: "https://merchant.com/terms/cancelation"
shipping_option_update
string
URL for shipping option update. (must be https, max 2000 characters) Example: "https://merchant.com/shippingoptionupdate"
address_update
string
URL for shipping, tax and purchase currency updates. Will be called on address changes. (must be https, max 2000 characters) Example: "https://merchant.com/addressupdate"
country_change
string
URL for shipping, tax and purchase currency updates. Will be called on billing or shipping country changes. (must be https, max 2000 characters) Example: "https://merchant.com/countrychange"
html_snippet
string
read only		The HTML snippet that is used to render the checkout in an iframe.
merchant_reference1
string
Used for storing merchant's internal order number or other reference. If set, will be shown on the confirmation page as "order number" . The value is also available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"
merchant_reference2
string
Used for storing merchant's internal order number or other reference. The value is available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"
started_at
string (datetime)
read only		ISO 8601 datetime. The date and time when the order has been created. The format will be as follows: "yyyy-mm-ddThh:mm:ssZ"
Read more about data types
completed_at
string (datetime)
read only		ISO 8601 datetime. The date and time when the order has been completed. The format will be as follows: "yyyy-mm-ddThh:mm:ssZ"
Read more about data types
last_modified_at
string (datetime)
read only		ISO 8601 datetime. The date and time when the order was last modified. The format will be as follows: "yyyy-mm-ddThh:mm:ssZ"
Read more about data types
external_payment_methods
array of payment_provider(object)
List of external payment methods that will be displayed as part of payment methods in the checkout.
Expand
Payment Provider Object
ParameterDescription
name
string
required		The name of the payment provider. (max 255 characters)
fee
integer
Minor units. Includes tax.
description
string
Description. (max 500 characters)
countries
array of strings
If specified, limits the method to the listed countries (alpha 2 codes).
label
string
Controls label of buy button
  • continue
  • complete
redirect_url
string
required		URL to redirect to. (must be https, min 7, max 2000 characters)
image_url
string
URL to an image to display. (must be https, max 2000 characters)
external_checkouts
array of payment_provider(object)
List of external checkouts that will be displayed as part of payment methods in the checkout. The image_url is required, and the image size has to be 276x48px
Expand
Payment Provider Object
ParameterDescription
name
string
required		The name of the payment provider. (max 255 characters)
fee
integer
Minor units. Includes tax.
description
string
Description. (max 500 characters)
countries
array of strings
If specified, limits the method to the listed countries (alpha 2 codes).
label
string
Controls label of buy button
  • continue
  • complete
redirect_url
string
required		URL to redirect to. (must be https, min 7, max 2000 characters)
image_url
string
URL to an image to display. (must be https, max 2000 characters)
shipping_countries
array of strings
List of allowed shipping countries for this order in ISO-3166 alpha-2 format. If specified, the customer will be able to change the shipping country in the checkout and you will be notified through ‘address_update’ callback or the ‘shipping_address_change’ javascript event. If not specified then the default value will be the purchase country. Example: look at billing_countries example.
shipping_options
array of shipping_option(object)
A list of shipping options available for this order.
Expand
Shipping Option Object
ParameterDescription
id
string
required		id
name
string
required		Name.
description
string
Description.
promo
string
Promotion name. To be used if this shipping option is promotional.
price
integer
required		Price including tax.
preselected
boolean
If true, this option will be preselected when checkout loads. Default: false
tax_amount
integer
required		Tax amount.
tax_rate
integer
required		Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
shipping_method
string
Shipping method. Possible values:
  • PickUpStore
  • Home
  • BoxReg
  • BoxUnreg
  • PickUpPoint
  • Own
  • Postal
  • DHLPackstation
  • Digital
If DHLPackstation is selected the correct form will be displayed.
delivery_details
object

Expand
DeliveryDetailsV1 Object
ParameterDescription
carrier
string
Carrier product name
class
string
Type of shipping class
product
object

Expand
ProductV1 Object
ParameterDescription
name
string
Carrier product name
identifier
string
Carrier product identifier
timeslot
object

Expand
TimeslotV1 Object
ParameterDescription
id
string
Id
start
string
Start time
end
string
End time
pickup_location
object

Expand
PickupLocationV1 Object
ParameterDescription
id
string
Id
name
string
Name of the location
address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
tms_reference
string
TMS reference. Required to map completed orders to shipments reserved in TMS.
selected_addons
array of selected_addon(object)

Expand
Selected Addon Object
ParameterDescription
type
string
price
integer
external_id
string
user_input
string
merchant_data
string
Pass through field to send any information about the order to be used later for reference while retrieving the order details (max 6000 characters).
merchant_requested
object

Expand
Merchant Requested Object
ParameterDescription
additional_checkbox
boolean
read only		Informs whether the additional_checkbox is checked or not, when applicable.
additional_checkboxes
array of merchant_requested_checkbox(object)
read only		Informs whether the additional_checkboxes is checked or not, when applicable.
Expand
Merchant Requested Checkbox Object
ParameterDescription
id
string
checked
boolean
selected_shipping_option
object

Expand
Shipping Option Object
ParameterDescription
id
string
required		id
name
string
required		Name.
description
string
Description.
promo
string
Promotion name. To be used if this shipping option is promotional.
price
integer
required		Price including tax.
preselected
boolean
If true, this option will be preselected when checkout loads. Default: false
tax_amount
integer
required		Tax amount.
tax_rate
integer
required		Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
shipping_method
string
Shipping method. Possible values:
  • PickUpStore
  • Home
  • BoxReg
  • BoxUnreg
  • PickUpPoint
  • Own
  • Postal
  • DHLPackstation
  • Digital
If DHLPackstation is selected the correct form will be displayed.
delivery_details
object

Expand
DeliveryDetailsV1 Object
ParameterDescription
carrier
string
Carrier product name
class
string
Type of shipping class
product
object

Expand
ProductV1 Object
ParameterDescription
name
string
Carrier product name
identifier
string
Carrier product identifier
timeslot
object

Expand
TimeslotV1 Object
ParameterDescription
id
string
Id
start
string
Start time
end
string
End time
pickup_location
object

Expand
PickupLocationV1 Object
ParameterDescription
id
string
Id
name
string
Name of the location
address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
tms_reference
string
TMS reference. Required to map completed orders to shipments reserved in TMS.
selected_addons
array of selected_addon(object)

Expand
Selected Addon Object
ParameterDescription
type
string
price
integer
external_id
string
user_input
string
recurring_token
string
read only		Token to be used when creating recurring orders.
recurring_description
string
read only		Description to be added to the recurring order.
billing_countries
array of strings
List of allowed billing countries for this order. If specified, the customer will be able to change the billing country in the checkout and you will be notified through ‘country_change’ callback or the ‘billing_address_change’ javascript event. If not specified but shipping_countries is specified, will use same values as shipping_countries. If not specified and shipping_countries is not specified, then the default value will be the purchase country. Example: ["AD", "AE", "AG", "AI", "AL", "AM", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CF", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GR", "GS", "GT", "GU", "GY", "HK", "HN", "HR", "HU", "ID", "IE", "IL", "IM", "IN", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SR", "ST", "SV", "SX", "SZ", "TC", "TF", "TG", "TH", "TJ", "TK", "TL", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YT", "ZA", "ZM", "ZW"]"

Retrieve an order

Request
Path:GET /checkout/v3/orders/{order_id}
See full example
Empty body request
Response
Description:successful operation
Headers:Status Code: 200
Content-Type: application/json
See full example
{
    "name": "Women's Fashion",
    "status": "CHECKOUT_INCOMPLETE",
    "locale": "en-US",
    "customer": {
        "type": "person",
        "gender": "male",
        "date_of_birth": "1995-10-20",
        "organization_registration_id": "556737-0431",
        "vat_id": "string"
    },
    "options": {
        "require_validate_callback_success": false,
        "acquiring_channel": "string",
        "vat_removed": false,
        "allow_separate_shipping_address": false,
        "color_button": "#FF9900",
        "color_button_text": "#FF9900",
        "color_checkbox": "#FF9900",
        "color_checkbox_checkmark": "#FF9900",
        "color_header": "#FF9900",
        "color_link": "#FF9900",
        "date_of_birth_mandatory": false,
        "shipping_details": "Delivered within 1-3 working days",
        "title_mandatory": false,
        "additional_checkbox": {
            "text": "Please add me to the newsletter list, read more here \link\",
            "checked": false,
            "required": false
        },
        "national_identification_number_mandatory": false,
        "additional_merchant_terms": "string",
        "phone_mandatory": false,
        "radius_border": "5",
        "allowed_customer_types": [
            "string"
        ],
        "show_subtotal_detail": false,
        "additional_checkboxes": 
            {
                "id": "newsletter_opt_in",
                "text": "Please add me to the newsletter list, read more here \[link\",
                "checked": false,
                "required": false
            }
        ],
        "verify_national_identification_number": false,
        "show_vat_registration_number_field": false
    },
    "attachment": {
        "body": "{\"hotel_reservation_details\": [{\"pnr\": \"VH67899\",\"hotel_intinerary\": [{\"hotel_name\": \"Hotel ltd.\",\"address\": {\"street_address\": \"Storgatan 3\",\"postal_code\": \"113 35\",\"city\": \"Stockholm\",\"country\": \"Sweden\"},\"start_time\": \"2019-01-31T15:00:00Z\",\"end_time\": \"2019-01-31T15:30:00Z\",\"number_of_rooms\": 2,\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@klarna.com\",\"hotel_price\": 23050,\"class\": \"Business\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"air_reservation_details\": [{\"pnr\": \"VH67899\",\"intinerary\": [{\"departure\": \"ARN\",\"departure_city\": \"Stockholm\",\"arrival\": \"NCE\",\"arrival_city\": \"Nice\",\"carrier\": \"SK\",\"segment_price\": 34000,\"departure_date\": \"2019-01-30T15:00:00Z\",\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@klarna.com\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"customer_account_info\": [{\"unique_account_identifier\": \"12345\",\"account_registration_date\": \"2016-01-24T15:00:00Z\",\"account_last_modified\": \"2017-01-24T15:00:00Z\"}],\"payment_history_full\": [{\"payment_option\": \"card\",\"number_paid_purchases\": 2,\"total_amount_paid_purchases\": 1234,\"date_of_last_paid_purchase\": \"2018-01-24T15:00:00Z\",\"date_of_first_paid_purchase\": \"2018-01-24T15:00:00Z\"}]}",
        "content_type": "application/vnd.klarna.internal.emd-v2+json"
    },
    "gui": {
        "options": [
            "string"
        ]
    },
    "recurring": false,
    "tags": [
        "string"
    ],
    "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
    "purchase_country": "US",
    "purchase_currency": "USD",
    "billing_address": {
        "given_name": "John",
        "family_name": "Doe",
        "organization_name": "string",
        "email": "john@doe.com",
        "title": "Mr",
        "street_address": "Lombard St 10",
        "street_address2": "Apt 214",
        "street_name": "Lombard St",
        "street_number": "10",
        "house_extension": "B",
        "postal_code": "90210",
        "city": "Beverly Hills",
        "region": "CA",
        "phone": "333444555",
        "country": "US",
        "care_of": "C/O",
        "reference": "string",
        "attention": "string"
    },
    "shipping_address": {
        "given_name": "John",
        "family_name": "Doe",
        "organization_name": "string",
        "email": "john@doe.com",
        "title": "Mr",
        "street_address": "Lombard St 10",
        "street_address2": "Apt 214",
        "street_name": "Lombard St",
        "street_number": "10",
        "house_extension": "B",
        "postal_code": "90210",
        "city": "Beverly Hills",
        "region": "CA",
        "phone": "333444555",
        "country": "US",
        "care_of": "C/O",
        "reference": "string",
        "attention": "string"
    },
    "order_amount": 50000,
    "order_tax_amount": 4545,
    "order_lines": [
        {
            "type": "physical",
            "reference": "19-402-USA",
            "name": "Red T-Shirt",
            "quantity": 5,
            "quantity_unit": "pcs",
            "unit_price": 10000,
            "tax_rate": 1000,
            "total_amount": 50000,
            "total_discount_amount": 0,
            "total_tax_amount": 4545,
            "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
            "product_url": "https://www.example.com/products/f2a8d7e34",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg",
            "product_identifiers": {
                "brand": "Intel",
                "category_path": "Electronics Store > Computers & Tablets > Desktops",
                "global_trade_item_number": "735858293167",
                "manufacturer_part_number": "BOXNUC5CPYH"
            },
            "shipping_attributes": {
                "weight": 1000,
                "dimensions": {
                    "height": 100,
                    "width": 100,
                    "length": 100
                },
                "tags": [
                    "string"
                ]
            }
        }
    ],
    "merchant_urls": {
        "terms": "https://www.example.com/terms.html",
        "checkout": "https://www.example.com/checkout.html",
        "confirmation": "https://www.example.com/confirmation.html",
        "push": "https://www.example.com/api/push",
        "validation": "https://www.example.com/api/validation",
        "notification": "https://www.example.com/api/pending",
        "cancellation_terms": "https://www.example.com/terms/cancellation.html",
        "shipping_option_update": "https://www.example.com/api/shipment",
        "address_update": "https://www.example.com/api/address",
        "country_change": "https://www.example.com/api/country"
    },
    "html_snippet": "<div id='klarna-checkout-container'><script>alert('Initializing Klarna Checkout');</script></div>",
    "merchant_reference1": "45aa52f387871e3a210645d4",
    "merchant_reference2": "45aa52f387871e3a210645d4",
    "started_at": "2021-09-14T08:54:32.858Z",
    "completed_at": "2021-09-14T08:54:32.858Z",
    "last_modified_at": "2021-09-14T08:54:32.858Z",
    "external_payment_methods": [
        {
            "name": "PayhereUs",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "string"
            ],
            "label": "continue",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg"
        }
    ],
    "external_checkouts": [
        {
            "name": "PayhereUs",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "string"
            ],
            "label": "continue",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg"
        }
    ],
    "shipping_countries": [
        "string"
    ],
    "shipping_options": [
        {
            "id": "express_priority",
            "name": "EXPRESS 1-2 Days",
            "description": "Delivery by 4:30 pm",
            "promo": "Christmas Promotion",
            "price": 0,
            "preselected": false,
            "tax_amount": 0,
            "tax_rate": 0,
            "shipping_method": "PickUpStore",
            "delivery_details": {
                "carrier": "string",
                "class": "string",
                "product": {
                    "name": "string",
                    "identifier": "string"
                },
                "timeslot": {
                    "id": "string",
                    "start": "string",
                    "end": "string"
                },
                "pickup_location": {
                    "id": "string",
                    "name": "string",
                    "address": {
                        "given_name": "John",
                        "family_name": "Doe",
                        "organization_name": "string",
                        "email": "john@doe.com",
                        "title": "Mr",
                        "street_address": "Lombard St 10",
                        "street_address2": "Apt 214",
                        "street_name": "Lombard St",
                        "street_number": "10",
                        "house_extension": "B",
                        "postal_code": "90210",
                        "city": "Beverly Hills",
                        "region": "CA",
                        "phone": "333444555",
                        "country": "US",
                        "care_of": "C/O",
                        "reference": "string",
                        "attention": "string"
                    }
                }
            },
            "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
            "selected_addons": [
                {
                    "type": "string",
                    "price": 0,
                    "external_id": "string",
                    "user_input": "string"
                }
            ]
        }
    ],
    "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
    "merchant_requested": {
        "additional_checkbox": false,
        "additional_checkboxes": [
            {
                "id": "string",
                "checked": false
            }
        ]
    },
    "selected_shipping_option": {
        "id": "express_priority",
        "name": "EXPRESS 1-2 Days",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "preselected": false,
        "tax_amount": 0,
        "tax_rate": 0,
        "shipping_method": "PickUpStore",
        "delivery_details": {
            "carrier": "string",
            "class": "string",
            "product": {
                "name": "string",
                "identifier": "string"
            },
            "timeslot": {
                "id": "string",
                "start": "string",
                "end": "string"
            },
            "pickup_location": {
                "id": "string",
                "name": "string",
                "address": {
                    "given_name": "John",
                    "family_name": "Doe",
                    "organization_name": "string",
                    "email": "john@doe.com",
                    "title": "Mr",
                    "street_address": "Lombard St 10",
                    "street_address2": "Apt 214",
                    "street_name": "Lombard St",
                    "street_number": "10",
                    "house_extension": "B",
                    "postal_code": "90210",
                    "city": "Beverly Hills",
                    "region": "CA",
                    "phone": "333444555",
                    "country": "US",
                    "care_of": "C/O",
                    "reference": "string",
                    "attention": "string"
                }
            }
        },
        "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
        "selected_addons": [
            {
                "type": "string",
                "price": 0,
                "external_id": "string",
                "user_input": "string"
            }
        ]
    },
    "recurring_token": "string",
    "recurring_description": "string",
    "billing_countries": [
        "string"
    ]
}
401You were not authorized to execute this operation. Show
{}
403Merchant was not activated. Show
{}
404We did not find any order with given ID. You need to create a new order. Show
{}
Code Examples
Use this API call to read an order from Klarna.

> Note that orders should only be read from the checkout API until the order is completed. Completed orders should be read using the order management API

Use this API call to read an order from Klarna.

Note that orders should only be read from the checkout API until the order is completed. Completed orders should be read using the order management API

HTTP Request

GET /checkout/v3/orders/{order_id}

Request parameters Response body

path collapse expand

ParameterDescription
order_id
string
ParameterDescription
name
string
read only		The merchant name (max 255 characters).
status
string
The current status of the order. The status will be ‘incomplete’ until the customer has been successfully authorized.
locale
string
required		Used to define the language and region of the customer. RFC 1766 customer's locale.
Read more about data types
customer
object

Expand
Customer Object
ParameterDescription
type
string
The default supported value is 'person'. If B2B is enabled for the merchant, the value may be "organization".
gender
string
Customer’s gender - ‘male’ or ‘female’.
date_of_birth
string
Customer’s date of birth. The format is ‘yyyy-mm-dd’. ISO 8601 date.
Read more about data types
organization_registration_id
string
"The organization's official registration id (organization number). Note: Applicable only for B2B orders."
vat_id
string
Organization VAT ID. Only applies for b2b orders.
options
object

Expand
Options Object
ParameterDescription
require_validate_callback_success
boolean
If true, validate callback must get a positive response to not stop purchase. Default: false.
acquiring_channel
string
Acquiring channel for the order. The possible values are:
  • MOTO for "Mail Order Telephone Order"
  • ECOMMERCE for "E-commerce"
  • IN_STORE for "Purchase in boutique"
  • TELESALES for "Telesales/telemarketing"
  • Default : ECOMMERCE
vat_removed
boolean
If true, VAT is not displayed in Checkout's Order Summary page.
allow_separate_shipping_address
boolean
If true, the consumer can enter different billing and shipping addresses. Default: false, except for purchase_country DE where default is: true
color_button
string
Color for the buttons within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_button_text
string
Color for the text inside the buttons within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_checkbox
string
Color for the checkboxes within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_checkbox_checkmark
string
Color for the checkboxes checkmark within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_header
string
Color for the headers within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
color_link
string
Color for the hyperlinks within the iFrame. Value should be a CSS hex color, e.g. "#FF9900"
date_of_birth_mandatory
boolean
If true, the consumer cannot skip date of birth. Default: false
shipping_details
string
A message that will be presented on the confirmation page under the headline "Delivery" (max 255 characters).
title_mandatory
boolean
If specified to false, title becomes optional. Only available for orders for country GB.
additional_checkbox
object

Expand
Checkbox Object
ParameterDescription
text
string
required		Text that will be displayed to the consumer aside the checkbox. Links and formatting can be added using Markdown. (max 1000 characters)
checked
boolean
required		Default state of the additional checkbox. It will use this value when loaded for the first time.
required
boolean
required		Whether it is required for the consumer to check the additional checkbox box or not in order to complete the purchase.
national_identification_number_mandatory
boolean
If true, the user cannot skip national identification number in SE, NO, FI and DK. Default: false. In order to read the national identification number in the validation callback, please contact Klarna’s merchant support.
additional_merchant_terms
string
Additional merchant defined field. e.g. Extra terms and conditions to show. Example: "ADDITIONAL MERCHANT TERMS! [terms link](https://merchant.com/extra_terms)"
phone_mandatory
boolean
If false, the consumer can skip the phone. Only available for orders in DACH countries.
radius_border
string
Radius for the border of elements within the iFrame.
allowed_customer_types
array of strings
A list of allowed customer types. Supported types: person & organization. Example: ["person","organization"]
show_subtotal_detail
boolean
If true, the Order Detail subtotals view is expanded when the Klarna Checkout iFrame is loaded. Default: false
additional_checkboxes
array of checkbox-v2(object)

Expand
Checkbox-v2 Object
ParameterDescription
id
string
required		Identifier used when presenting data back to merchant
text
string
required		Text that will be displayed to the consumer aside the checkbox. Links and formatting can be added using Markdown. (max 1000 characters)
checked
boolean
required		Default state of the additional checkbox. It will use this value when loaded for the first time.
required
boolean
required		Whether it is required for the consumer to check the additional checkbox box or not in order to complete the purchase.
verify_national_identification_number
boolean
Enable verification of National Identification Numbers only in Sweden, Finland and Norway. This option also make the national identification number mandatory. (Not applicable for countries outside of Sweden, Finland and Norway)
show_vat_registration_number_field
boolean
If true, a optional VAT registration number field will be shown in the address form. Only applies for b2b orders.
attachment
object

Expand
Attachment Object
ParameterDescription
body
string
required		The content of the extra merchant data which should be presented as a string inside this property. The body should be an object containing any of the keys and sub objects described below serialised to JSON. More information on that object can be found here.
Expand
ParameterDescription
air_reservation_details
array of air_reservation_details(object)
Details about the reservation of airline tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
IATA Airport Code (three letters)
departure_city
string
arrival
string
IATA Airport Code (three letters)
arrival_city
string
carrier
string
IATA Airline standard (two letters or digits)
segment_price
number
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
bus_reservation_details
array of bus_reservation_details(object)
Details about the reservation of bus tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
City code or name
departure_city
string
arrival
string
City code or name
arrival_city
string
carrier
string
Name of transportation company
segment_price
integer
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
train_reservation_details
array of train_reservation_details(object)
Details about the reservation of train tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
City code or name
departure_city
string
arrival
string
City code or name
arrival_city
string
carrier
string
Name of transportation company
segment_price
integer
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
ferry_reservation_details
array of ferry_reservation_details(object)
Details about the reservation of ferry tickets
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
itinerary
array of itinerary(object)
Itinerary data, one per segment
Expand
ParameterDescription
departure
string
City code or name
departure_city
string
arrival
string
City code or name
arrival_city
string
carrier
string
Name of transportation company
segment_price
integer
Local currency
departure_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
passenger_id
array of passenger_id(integer)
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
hotel_reservation_details
array of hotel_reservation_details(object)
Details about the reservation of hotel rooms
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
hotel_itinerary
array of hotel_itinerary(object)
Hotel itinerary data, one per hotel stay
Expand
ParameterDescription
hotel_name
string
Name of hotel
address
object

Expand
Address Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
number_of_rooms
integer
passenger_id
array of passenger_id(integer)
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
hotel_price
number
Local currency
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
passengers
array of Person(object)
Passengers data
Expand
Person Object
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
car_rental_reservation_details
array of car_rental_reservation_details(object)
Details about the reservation of rental cars
Expand
ParameterDescription
pnr
string
Trip booking number, e.g. VH67899
car_rental_itinerary
array of car_rental_itinerary(object)
Car rental itinerary data
Expand
ParameterDescription
rental_company
string
Name of rental company
drivers_id
array of drivers_id(integer)
pick_up_location
object

Expand
Pick Up Location Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
drop_off_location
object

Expand
Drop Off Location Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
car_price
number
Local currency
class
string
insurance
array of insurance(object)
Insurance data
Expand
ParameterDescription
insurance_company
string
insurance_type
undefined
  • cancellation
  • travel
  • cancellation_travel
  • bankruptcy
insurance_price
number
Local currency
drivers
array of drivers(object)

Expand
ParameterDescription
id
integer
title
undefined
Mr, Mrs, Ms or blank if under 12 years
  • mr
  • mrs
  • ms
first_name
string
last_name
string
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
event
array of event(object)

Expand
ParameterDescription
event_name
string
Name of the event, e.g. "Fancy Singer"
event_company
string
Name of the company arranging the event, e.g. "Happy Parties Ltd."
genre_of_event
string
Category or type of venue, "Pop"
arena_name
string
Name of the venue, "Song Arena"
arena_location
object
Location of the arena.
Expand
Location Object
ParameterDescription
street_address
string
postal_code
string
city
string
country
string
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
access_controlled_venue
boolean
Tickets are digitally checked when enetering the venue
ticket_delivery_method
undefined
  • pick_up
  • email
  • post
  • phone
ticket_delivery_recipient
string
The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
voucher
array of voucher(object)

Expand
ParameterDescription
voucher_name
string
Description of the product the voucher entitles to, e.g. "China trip"
voucher_company
string
Name of the company that will provide good / service upon voucher (not the same as the selling merchant), e.g. "Sun Trips Ltd."
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
subscription
array of subscription(object)

Expand
ParameterDescription
subscription_name
string
Name of the product on subscription, e.g. "Contact lenses"
start_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
end_time
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
auto_renewal_of_subscription
boolean
Info whether the subscription will be auto renewed upon expiry.
affiliate_name
string
Name of the affiliate that originated the purchase. If none, leave blank.
marketplace_seller_info
array of marketplace_seller_info(object)

Expand
ParameterDescription
unique_account_identifier_seller
object

Expand
Unique Account Identifier Seller Object
ParameterDescription
email
string
pno
string
other
string
sub_merchant_id
string
Name or unique number of the selling / delivering merchant, e.g. "Marketbrick Ltd."
product_category
string
Name of the overall category to which the specific good(s) belong to, according to the selling merchants categorization. E.g. "Computers"
product_name
string
Name of the specific good purchased, e.g. "Acer 5400"
account_registration_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
account_last_modified
object

Expand
Account Last Modified Object
ParameterDescription
password
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
email
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
listing
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
login
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
address
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
seller_rating
number
Current rating. Partner should provide upfront their rating scale, e.g. 65
number_of_trades
integer
Number of trades the sub-merchant did since 12 months back, e.g. 23
volume_of_trades
integer
Volumes of trades the sub-merchant did since 12 months back, e.g. 230.5
marketplace_winner_info
array of marketplace_winner_info(object)

Expand
ParameterDescription
unique_account_identifier_winner
object

Expand
Unique Account Identifier Winner Object
ParameterDescription
email
string
pno
string
other
string
account_registration_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
account_last_modified
object

Expand
Account Last Modified Object
ParameterDescription
password
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
email
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
listing
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
login
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
address
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
number_of_trades
integer
Number of trades the winner did since 12 months back, e.g. 5
volume_of_trades
integer
Volume of trades the winner did since 12 months back, 230.5
customer_account_info
array of customer_account_info(object)

Expand
ParameterDescription
unique_account_identifier
string
Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
account_registration_date
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
account_last_modified
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
payment_history_full
array of payment_history_full(object)

Expand
ParameterDescription
unique_account_identifier
string
Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
payment_option
string
  • card
  • direct banking
  • non klarna credit
  • sms
  • other
number_paid_purchases
integer
Total number of successful purchases
total_amount_paid_purchases
number
Total amount of successful purchases (local currency), e.g. 1234.00
date_of_last_paid_purchase
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
date_of_first_paid_purchase
string (datetime)
ISO 8601 e.g. 2012-11-24T15:00
Read more about data types
payment_history_simple
array of payment_history_simple(object)

Expand
ParameterDescription
unique_account_identifier
string
Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
paid_before
boolean
Whether the customer has paid before or not
other_delivery_address
array of other_delivery_address(object)

Expand
ParameterDescription
shipping_method
undefined
  • store pick-up
  • pick-up point
  • registered box
  • unregistered box
shipping_type
undefined
  • normal
  • express
first_name
string
last_name
string
street_address
string
street_number
string
postal_code
string
city
string
country
string
content_type
string
required		The content type of the body. It is usually represented as "application/vnd.klarna.internal.emd-v2+json"
gui
object

Expand
Gui Object
ParameterDescription
options
array of strings
An array of options to define the checkout behaviour. Supported options: minimal_confirmation. The gui object is an array of options to modify checkout client ui behaviours. Examples: ["minimal_confirmation"]
recurring
boolean
Indicates whether this purchase will create a token that can be used by the merchant to create recurring purchases. This must be enabled for the merchant to use. Default: false Depending on specified country, recurring could be used for the following payment methods: Pay Later, Direct Debit, Card.
tags
array of strings
Extra information added to the order. Example: ["dangerous_goods", "bulky"]
order_id
string
read only		Unique order ID that will be used for the entire lifecycle of the order. (max 255 characters)
purchase_country
string
required		The purchase country of the merchant's store. The format to be used is ISO 3166 alpha-2. Eg: GB, SE, DE, US, etc. Note: purchase country and currency need to match the defined merchant configuration. For global configuration read this https://developers.klarna.com/documentation/klarna-checkout/kco-global/
Read more about data types
purchase_currency
string
required		The purchase currency of the merchant's store. The format to be used is ISO 4217. Eg: USD, EUR, SEK, GBP, etc. Note: purchase country and currency need to match the defined merchant configuration. For global configuration read this https://developers.klarna.com/documentation/klarna-checkout/kco-global/
Read more about data types
billing_address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
shipping_address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
order_amount
integer
required		Total amount of the order including tax and any available discounts. The value should be in non-negative minor units. Example: 25 Euros should be 2500.
order_tax_amount
integer
required		Total tax amount of the order. The value should be in non-negative minor units. Example: 25 Euros should be 2500.
order_lines
array of order_line(object)
required		An array containing list of line items that are part of this order. Maximum of 1000 line items could be processed in a single order.
Expand
Order Line Object
ParameterDescription
type
string
Type of the order line item. The possible values are:
  • physical (physical good)
  • discount
  • shipping_fee
  • sales_tax (depends on the country/city, usually called VAT)
  • digital (digital good)
  • gift_card
  • store_credit (credit from the merchant)
  • surcharge (extra charge)
reference
string
Article number, SKU or similar. (max 64 characters)
name
string
required		Descriptive name of the order line item (max 255 characters)
quantity
integer
required		Non-negative number. Quantity of the order line item.
quantity_unit
string
Unit used to describe the quantity, e.g. kg, pcs... If defined has to be 1-8 characters
unit_price
integer
required		Minor units. Includes tax, excludes discount. (max value: 100000000). Example: 100 Euros should be 10000.
tax_rate
integer
required		Non-negative value. The percentage value is represented with two implicit decimals. (max 10000) Example: 25% should be 2500.
total_amount
integer
required		Minor units. Includes tax and discount. Example: 25 euros should be 2500 Value = (quantity x unit_price) - total_discount_amount. (max value: 100000000)
total_discount_amount
integer
Non-negative minor units. Includes tax. Example: 25 euros should be 2500
total_tax_amount
integer
required		Must be within ±1 of total_amount - total_amount * 10000 / (10000 + tax_rate). Negative when type is discount.
merchant_data
string
Property used to store additional metadata per item that will be returned whenever an order is read from Klarna. Pass through field. (max 1024 characters).
product_url
string
URL to the product page that can be later embedded in communications between Klarna and the customer. (max 1024 characters)
image_url
string
URL to an image that can be later embedded in communications between Klarna and the customer. (max 1024 characters) Improves post-purchase customer experiences.
product_identifiers
object

Expand
Product Identifiers Object
ParameterDescription
brand
string
The product's brand name as generally recognized by consumers. If no brand is available for a product, do not supply any value.
category_path
string
The product's category path as used in the merchant's webshop. Include the full and most detailed category and separate the segments with ' > '. (max 750 characters) Example: "Electronics Store > Computers & Tablets > Desktops"
global_trade_item_number
string
The product's Global Trade Item Number (GTIN). Common types of GTIN are EAN, ISBN or UPC. Exclude dashes and spaces, where possible
manufacturer_part_number
string
The product's Manufacturer Part Number (MPN), which - together with the brand - uniquely identifies a product. Only submit MPNs assigned by a manufacturer and use the most specific MPN possible
shipping_attributes
object

Expand
Shipping Attributes Object
ParameterDescription
weight
integer
The product's weight as used in the merchant's webshop. Non-negative. Measured in grams.
dimensions
object

Expand
Dimensions Object
ParameterDescription
height
integer
The product's height as used in the merchant's webshop. Non-negative. Measured in millimeters.
width
integer
The product's width as used in the merchant's webshop. Non-negative. Measured in millimeters.
length
integer
The product's length as used in the merchant's webshop. Non-negative. Measured in millimeters.
tags
array of strings
The product's extra features, example ["dangerous_goods", "bulky"]
merchant_urls
object

Expand
Merchant Urls Object
ParameterDescription
terms
string
required		URL for the terms and conditions page of the merchant. The URL will be displayed inside the Klarna Checkout iFrame.(max 2000 characters) Example: "https://merchant.com/terms"
checkout
string
required		URL for the checkout page of the merchant. (max 2000 characters) Example: "https://merchant.com/checkout"
confirmation
string
required		URL of the merchant confirmation page. The consumer will be redirected back to the confirmation page if the authorization is successful after the customer clicks on the ‘Place Order’ button inside checkout. The special characters of the confirmation URL should be encoded, e.g. the "space" character should be written as "%20". Then, on top of that, the whole confirmation URL should be encoded. E.g. the "space" character should become "%2520". (max 2000 characters) Example: "https://merchant.com/confirmation"
push
string
required		URL that will be used for push notification when an order is completed. Should be different than checkout and confirmation URLs. (max 2000 characters) Example: "https://merchant.com/push"
validation
string
URL that will be requested for final merchant validation. (must be https, max 2000 characters) Example: "https://merchant.com/validation"
notification
string
URL for notifications on pending orders. (max 2000 characters) Example: "https://merchant.com/notification/{checkout.order.id}"
cancellation_terms
string
URL for the cancellation terms page of the merchant. The URL will be displayed in the email that is sent to the customer after the order is captured.(max 2000 characters) Example: "https://merchant.com/terms/cancelation"
shipping_option_update
string
URL for shipping option update. (must be https, max 2000 characters) Example: "https://merchant.com/shippingoptionupdate"
address_update
string
URL for shipping, tax and purchase currency updates. Will be called on address changes. (must be https, max 2000 characters) Example: "https://merchant.com/addressupdate"
country_change
string
URL for shipping, tax and purchase currency updates. Will be called on billing or shipping country changes. (must be https, max 2000 characters) Example: "https://merchant.com/countrychange"
html_snippet
string
read only		The HTML snippet that is used to render the checkout in an iframe.
merchant_reference1
string
Used for storing merchant's internal order number or other reference. If set, will be shown on the confirmation page as "order number" . The value is also available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"
merchant_reference2
string
Used for storing merchant's internal order number or other reference. The value is available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"
started_at
string (datetime)
read only		ISO 8601 datetime. The date and time when the order has been created. The format will be as follows: "yyyy-mm-ddThh:mm:ssZ"
Read more about data types
completed_at
string (datetime)
read only		ISO 8601 datetime. The date and time when the order has been completed. The format will be as follows: "yyyy-mm-ddThh:mm:ssZ"
Read more about data types
last_modified_at
string (datetime)
read only		ISO 8601 datetime. The date and time when the order was last modified. The format will be as follows: "yyyy-mm-ddThh:mm:ssZ"
Read more about data types
external_payment_methods
array of payment_provider(object)
List of external payment methods that will be displayed as part of payment methods in the checkout.
Expand
Payment Provider Object
ParameterDescription
name
string
required		The name of the payment provider. (max 255 characters)
fee
integer
Minor units. Includes tax.
description
string
Description. (max 500 characters)
countries
array of strings
If specified, limits the method to the listed countries (alpha 2 codes).
label
string
Controls label of buy button
  • continue
  • complete
redirect_url
string
required		URL to redirect to. (must be https, min 7, max 2000 characters)
image_url
string
URL to an image to display. (must be https, max 2000 characters)
external_checkouts
array of payment_provider(object)
List of external checkouts that will be displayed as part of payment methods in the checkout. The image_url is required, and the image size has to be 276x48px
Expand
Payment Provider Object
ParameterDescription
name
string
required		The name of the payment provider. (max 255 characters)
fee
integer
Minor units. Includes tax.
description
string
Description. (max 500 characters)
countries
array of strings
If specified, limits the method to the listed countries (alpha 2 codes).
label
string
Controls label of buy button
  • continue
  • complete
redirect_url
string
required		URL to redirect to. (must be https, min 7, max 2000 characters)
image_url
string
URL to an image to display. (must be https, max 2000 characters)
shipping_countries
array of strings
List of allowed shipping countries for this order in ISO-3166 alpha-2 format. If specified, the customer will be able to change the shipping country in the checkout and you will be notified through ‘address_update’ callback or the ‘shipping_address_change’ javascript event. If not specified then the default value will be the purchase country. Example: look at billing_countries example.
shipping_options
array of shipping_option(object)
A list of shipping options available for this order.
Expand
Shipping Option Object
ParameterDescription
id
string
required		id
name
string
required		Name.
description
string
Description.
promo
string
Promotion name. To be used if this shipping option is promotional.
price
integer
required		Price including tax.
preselected
boolean
If true, this option will be preselected when checkout loads. Default: false
tax_amount
integer
required		Tax amount.
tax_rate
integer
required		Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
shipping_method
string
Shipping method. Possible values:
  • PickUpStore
  • Home
  • BoxReg
  • BoxUnreg
  • PickUpPoint
  • Own
  • Postal
  • DHLPackstation
  • Digital
If DHLPackstation is selected the correct form will be displayed.
delivery_details
object

Expand
DeliveryDetailsV1 Object
ParameterDescription
carrier
string
Carrier product name
class
string
Type of shipping class
product
object

Expand
ProductV1 Object
ParameterDescription
name
string
Carrier product name
identifier
string
Carrier product identifier
timeslot
object

Expand
TimeslotV1 Object
ParameterDescription
id
string
Id
start
string
Start time
end
string
End time
pickup_location
object

Expand
PickupLocationV1 Object
ParameterDescription
id
string
Id
name
string
Name of the location
address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
tms_reference
string
TMS reference. Required to map completed orders to shipments reserved in TMS.
selected_addons
array of selected_addon(object)

Expand
Selected Addon Object
ParameterDescription
type
string
price
integer
external_id
string
user_input
string
merchant_data
string
Pass through field to send any information about the order to be used later for reference while retrieving the order details (max 6000 characters).
merchant_requested
object

Expand
Merchant Requested Object
ParameterDescription
additional_checkbox
boolean
read only		Informs whether the additional_checkbox is checked or not, when applicable.
additional_checkboxes
array of merchant_requested_checkbox(object)
read only		Informs whether the additional_checkboxes is checked or not, when applicable.
Expand
Merchant Requested Checkbox Object
ParameterDescription
id
string
checked
boolean
selected_shipping_option
object

Expand
Shipping Option Object
ParameterDescription
id
string
required		id
name
string
required		Name.
description
string
Description.
promo
string
Promotion name. To be used if this shipping option is promotional.
price
integer
required		Price including tax.
preselected
boolean
If true, this option will be preselected when checkout loads. Default: false
tax_amount
integer
required		Tax amount.
tax_rate
integer
required		Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
shipping_method
string
Shipping method. Possible values:
  • PickUpStore
  • Home
  • BoxReg
  • BoxUnreg
  • PickUpPoint
  • Own
  • Postal
  • DHLPackstation
  • Digital
If DHLPackstation is selected the correct form will be displayed.
delivery_details
object

Expand
DeliveryDetailsV1 Object
ParameterDescription
carrier
string
Carrier product name
class
string
Type of shipping class
product
object

Expand
ProductV1 Object
ParameterDescription
name
string
Carrier product name
identifier
string
Carrier product identifier
timeslot
object

Expand
TimeslotV1 Object
ParameterDescription
id
string
Id
start
string
Start time
end
string
End time
pickup_location
object

Expand
PickupLocationV1 Object
ParameterDescription
id
string
Id
name
string
Name of the location
address
object

Expand
Address Object
ParameterDescription
given_name
string
Given name.
family_name
string
Family name.
organization_name
string
email
string
E-mail address.
title
string
Title.

Valid values for UK:

  • Mr
  • Ms
  • Mrs
  • Miss

Valid values for DACH:

  • Herr
  • Frau

Valid values for NL:

  • Dhr.
  • Mevr.
street_address
string
Street address, first line.
street_address2
string
Street address, second line.
street_name
string
Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
street_number
string
Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
house_extension
string
House extension. Only applicable in NL
postal_code
string
Postal/post code.
city
string
City.
region
string
State or Region.
phone
string
Phone number.
country
string
ISO 3166 alpha-2. Country.
Read more about data types
care_of
string
Care of.
reference
string
attention
string
tms_reference
string
TMS reference. Required to map completed orders to shipments reserved in TMS.
selected_addons
array of selected_addon(object)

Expand
Selected Addon Object
ParameterDescription
type
string
price
integer
external_id
string
user_input
string
recurring_token
string
read only		Token to be used when creating recurring orders.
recurring_description
string
read only		Description to be added to the recurring order.
billing_countries
array of strings
List of allowed billing countries for this order. If specified, the customer will be able to change the billing country in the checkout and you will be notified through ‘country_change’ callback or the ‘billing_address_change’ javascript event. If not specified but shipping_countries is specified, will use same values as shipping_countries. If not specified and shipping_countries is not specified, then the default value will be the purchase country. Example: ["AD", "AE", "AG", "AI", "AL", "AM", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CF", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GR", "GS", "GT", "GU", "GY", "HK", "HN", "HR", "HU", "ID", "IE", "IL", "IM", "IN", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SR", "ST", "SV", "SX", "SZ", "TC", "TF", "TG", "TH", "TJ", "TK", "TL", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YT", "ZA", "ZM", "ZW"]"

Update an order

Request
Path:POST /checkout/v3/orders/{order_id}
Headers:Content-Type: application/json
See full example
{
    "name": "Women's Fashion",
    "status": "CHECKOUT_INCOMPLETE",
    "locale": "en-US",
    "customer": {
        "type": "person",
        "gender": "male",
        "date_of_birth": "1995-10-20",
        "organization_registration_id": "556737-0431",
        "vat_id": "string"
    },
    "options": {
        "require_validate_callback_success": false,
        "acquiring_channel": "string",
        "vat_removed": false,
        "allow_separate_shipping_address": false,
        "color_button": "#FF9900",
        "color_button_text": "#FF9900",
        "color_checkbox": "#FF9900",
        "color_checkbox_checkmark": "#FF9900",
        "color_header": "#FF9900",
        "color_link": "#FF9900",
        "date_of_birth_mandatory": false,
        "shipping_details": "Delivered within 1-3 working days",
        "title_mandatory": false,
        "additional_checkbox": {
            "text": "Please add me to the newsletter list, read more here \link\",
            "checked": false,
            "required": false
        },
        "national_identification_number_mandatory": false,
        "additional_merchant_terms": "string",
        "phone_mandatory": false,
        "radius_border": "5",
        "allowed_customer_types": [
            "string"
        ],
        "show_subtotal_detail": false,
        "additional_checkboxes": 
            {
                "id": "newsletter_opt_in",
                "text": "Please add me to the newsletter list, read more here \[link\",
                "checked": false,
                "required": false
            }
        ],
        "verify_national_identification_number": false,
        "show_vat_registration_number_field": false
    },
    "attachment": {
        "body": "{\"hotel_reservation_details\": [{\"pnr\": \"VH67899\",\"hotel_intinerary\": [{\"hotel_name\": \"Hotel ltd.\",\"address\": {\"street_address\": \"Storgatan 3\",\"postal_code\": \"113 35\",\"city\": \"Stockholm\",\"country\": \"Sweden\"},\"start_time\": \"2019-01-31T15:00:00Z\",\"end_time\": \"2019-01-31T15:30:00Z\",\"number_of_rooms\": 2,\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@klarna.com\",\"hotel_price\": 23050,\"class\": \"Business\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"air_reservation_details\": [{\"pnr\": \"VH67899\",\"intinerary\": [{\"departure\": \"ARN\",\"departure_city\": \"Stockholm\",\"arrival\": \"NCE\",\"arrival_city\": \"Nice\",\"carrier\": \"SK\",\"segment_price\": 34000,\"departure_date\": \"2019-01-30T15:00:00Z\",\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@klarna.com\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"customer_account_info\": [{\"unique_account_identifier\": \"12345\",\"account_registration_date\": \"2016-01-24T15:00:00Z\",\"account_last_modified\": \"2017-01-24T15:00:00Z\"}],\"payment_history_full\": [{\"payment_option\": \"card\",\"number_paid_purchases\": 2,\"total_amount_paid_purchases\": 1234,\"date_of_last_paid_purchase\": \"2018-01-24T15:00:00Z\",\"date_of_first_paid_purchase\": \"2018-01-24T15:00:00Z\"}]}",
        "content_type": "application/vnd.klarna.internal.emd-v2+json"
    },
    "gui": {
        "options": [
            "string"
        ]
    },
    "recurring": false,
    "tags": [
        "string"
    ],
    "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
    "purchase_country": "US",
    "purchase_currency": "USD",
    "billing_address": {
        "given_name": "John",
        "family_name": "Doe",
        "organization_name": "string",
        "email": "john@doe.com",
        "title": "Mr",
        "street_address": "Lombard St 10",
        "street_address2": "Apt 214",
        "street_name": "Lombard St",
        "street_number": "10",
        "house_extension": "B",
        "postal_code": "90210",
        "city": "Beverly Hills",
        "region": "CA",
        "phone": "333444555",
        "country": "US",
        "care_of": "C/O",
        "reference": "string",
        "attention": "string"
    },
    "shipping_address": {
        "given_name": "John",
        "family_name": "Doe",
        "organization_name": "string",
        "email": "john@doe.com",
        "title": "Mr",
        "street_address": "Lombard St 10",
        "street_address2": "Apt 214",
        "street_name": "Lombard St",
        "street_number": "10",
        "house_extension": "B",
        "postal_code": "90210",
        "city": "Beverly Hills",
        "region": "CA",
        "phone": "333444555",
        "country": "US",
        "care_of": "C/O",
        "reference": "string",
        "attention": "string"
    },
    "order_amount": 50000,
    "order_tax_amount": 4545,
    "order_lines": [
        {
            "type": "physical",
            "reference": "19-402-USA",
            "name": "Red T-Shirt",
            "quantity": 5,
            "quantity_unit": "pcs",
            "unit_price": 10000,
            "tax_rate": 1000,
            "total_amount": 50000,
            "total_discount_amount": 0,
            "total_tax_amount": 4545,
            "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
            "product_url": "https://www.example.com/products/f2a8d7e34",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg",
            "product_identifiers": {
                "brand": "Intel",
                "category_path": "Electronics Store > Computers & Tablets > Desktops",
                "global_trade_item_number": "735858293167",
                "manufacturer_part_number": "BOXNUC5CPYH"
            },
            "shipping_attributes": {
                "weight": 1000,
                "dimensions": {
                    "height": 100,
                    "width": 100,
                    "length": 100
                },
                "tags": [
                    "string"
                ]
            }
        }
    ],
    "merchant_urls": {
        "terms": "https://www.example.com/terms.html",
        "checkout": "https://www.example.com/checkout.html",
        "confirmation": "https://www.example.com/confirmation.html",
        "push": "https://www.example.com/api/push",
        "validation": "https://www.example.com/api/validation",
        "notification": "https://www.example.com/api/pending",
        "cancellation_terms": "https://www.example.com/terms/cancellation.html",
        "shipping_option_update": "https://www.example.com/api/shipment",
        "address_update": "https://www.example.com/api/address",
        "country_change": "https://www.example.com/api/country"
    },
    "html_snippet": "<div id='klarna-checkout-container'><script>alert('Initializing Klarna Checkout');</script></div>",
    "merchant_reference1": "45aa52f387871e3a210645d4",
    "merchant_reference2": "45aa52f387871e3a210645d4",
    "started_at": "2021-09-14T08:54:32.858Z",
    "completed_at": "2021-09-14T08:54:32.858Z",
    "last_modified_at": "2021-09-14T08:54:32.858Z",
    "external_payment_methods": [
        {
            "name": "PayhereUs",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "string"
            ],
            "label": "continue",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg"
        }
    ],
    "external_checkouts": [
        {
            "name": "PayhereUs",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "string"
            ],
            "label": "continue",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg"
        }
    ],
    "shipping_countries": [
        "string"
    ],
    "shipping_options": [
        {
            "id": "express_priority",
            "name": "EXPRESS 1-2 Days",
            "description": "Delivery by 4:30 pm",
            "promo": "Christmas Promotion",
            "price": 0,
            "preselected": false,
            "tax_amount": 0,
            "tax_rate": 0,
            "shipping_method": "PickUpStore",
            "delivery_details": {
                "carrier": "string",
                "class": "string",
                "product": {
                    "nam