Klarna API Reference

Search

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)

Europe: https://api.klarna.com/
North America: https://api-na.klarna.com/
Oceania: https://api-oc.klarna.com/

Base URLs - Testing (playground)

Europe: https://api.playground.klarna.com/
North America: https://api-na.playground.klarna.com/
Oceania: https://api-oc.playground.klarna.com/

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).

The error_code value is an ALL_CAPS_SNAKE_CASED and enumerable as appropriate per service (e.g., INVALID_POSTAL_CODE). The intent of the error_code is that it is machine readable and so that you can act properly solely on its value.
The error_message value is a human readable English message to aid in debugging. The error_message is not meant to be displayable to end-users, nor it is meant to be machine readable. It should be seen as something that the client would log to aid in the debugging, but it's never meant to be in any way parsed by the client. The error_message should not be internationalized. If internationalization of error messages is necessary to show an end user, then it should always be possible to do that on the client side based on the error_code.

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

Addition of a response body when one didn't previously exist
Addition of optional or read-only fields/properties
Re-ordering of fields in the JSON
Addition of HTTP headers
Addition of new values to an enum if there is a default defined
Addition of new HTTP methods to existing resources

Guidelines

Accept any 2xx codes as success, do not code for a specific error response code
Interpret any 4xx as an error, do not code for a specific error response code
Interpret any 5xx as an error, do not code for a specific error response code

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-06-16T07:31:03.056Z",
    "completed_at": "2021-06-16T07:31:03.056Z",
    "last_modified_at": "2021-06-16T07:31:03.056Z",
    "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-06-16T07:31:03.056Z",
    "completed_at": "2021-06-16T07:31:03.056Z",
    "last_modified_at": "2021-06-16T07:31:03.056Z",
    "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"
    ]
}

400	We 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" ] }`
401	You 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

Parameter

Description

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

401	You were not authorized to execute this operation. Show
`{}`
403	Merchant was not activated. Show
`{}`
404	We did not find any order with given ID. You need to create a new order. Show
`{}`

Path:	POST /checkout/v3/orders/{order_id}
Headers:	Content-Type: application/json

Merchant APIs

Klarna Bank Account

Klarna API Reference

Search

Introduction

API URLs

Base URLs - Live (production)

Base URLs - Testing (playground)

Authentication

Errors

Location Headers

Metadata

Data Types

Currency

Amount

Strings

Dates

Locale & Country

Encoding

Attachment Schema

API Updates

Non-breaking changes

Guidelines

Checkout API

Order

Create a new order

HTTP Request

body collapse expand

Retrieve an order

HTTP Request

path collapse expand

Update an order