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.

Examples:

2015-08-10T07:45:00Z representing the 10th of August 2015 at 07:45:00 and the UTC timezone.
2015-08-10T07:45:00.098Z representing the 10th of August 2015 at 07:45:00, with factional seconds 98 (98 milliseconds) 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 Rate Limiting

Klarna uses a number of measures to ensure stable operations for Klarna services, one of which is API rate limiting. If you send too many requests in a short amount of time, your requests may be subject to rate limiting.

A rate-limited request will return both:

a client error using HTTP-status code 429
HTTP headers containing information about the current limit and when the API quota is set

Each request will also return a header value indicating the remaining quota with every response.

Rate limits are measured per merchant_id, not per API credential. Rate limiting is measured on a per-operation basis and categorizes operations as either “create-session” or other operations. If a merchant_id has entered rate limiting, all subsequent requests will be returned with a rate limit status code until the rate limit resets.

Production environments: the API rate limit is 20 create-sessions per second on average measured over a 1 minute period. For the other operations, the API limit is 200 requests per second on average, measured over a 1 minute period. API request rates should not exceed two times the average rate.

Playground environments: the API rate limit is one quarter (1/4th) of the rate limits of production environments.

If you are frequently experiencing rate limitations, contact Merchant Support (https://www.klarna.com/merchant-support/) for advice on how to remedy the situation.

We may change rate limits to prevent abuse or address poorly behaving integrations.

Rate Limit Information

The following headers are used to indicate the status of the rate-limiting:

X-Ratelimit-Limit - Information on the rate limit and the metering interval
X-Ratelimit-Reset - How many seconds remain until the current metering interval resets
X-Ratelimit-Remaining - The approximate remaining quota of the rate limit

Example Response Headers

X-Ratelimit-Limit: 6000, 6000;w=60
X-Ratelimit-Remaining: 3456
X-Ratelimit-Reset: 43

The information returned with the response to the right should be interpreted as follows:

Rate limit quota for the interval is 6000 requests
The quota window interval is 60 seconds
There are 3456 requests remaining within the 60 second time window before further requests are rejected
There are 43 seconds until this quota resets

Handling Rate limiting gracefully

If you receive HTTP status code 429, we recommend that you use a retry mechanism with exponential back-off. We also highly recommend adding some jitter to the back-off to prevent retry requests from being retried all at the same time (which may trigger further rate limiting).

To further reduce any rate limiting, we also suggest that you use a token bucket algorithm to control the global flow of requests from the calling system to the API.

Common causes, mitigation, and support

We try to set the rate limiting quotas such that the vast majority of merchants are never rate limited for legitimate traffic. However, you might still encounter a rate limit in the following situations:

A high rate of requests within a short time period can trigger rate limiting. In order to mitigate this, we recommend that you pace your requests over the full interval indicated by the informational headers, and do retries with exponential backoff.
A sudden, large increase in traffic (for example, as a result of a flash sale) can exhaust the rate limit quota. If you anticipate that an upcoming event will exceed your request quota, please contact Merchant Support (https://www.klarna.com/merchant-support/) for assistance.

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

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

{
    "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
    "name": "Women's Fashion",
    "purchase_country": "US",
    "purchase_currency": "USD",
    "locale": "en-US",
    "status": "CHECKOUT_INCOMPLETE",
    "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"
                ]
            }
        }
    ],
    "customer": {
        "type": "person",
        "gender": "male",
        "date_of_birth": "1995-10-20",
        "organization_registration_id": "556737-0431",
        "vat_id": "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": "2022-06-08T07:03:49.501Z",
    "completed_at": "2022-06-08T07:03:49.501Z",
    "last_modified_at": "2022-06-08T07:03:49.501Z",
    "options": {
        "require_validate_callback_success": true,
        "acquiring_channel": "string",
        "vat_removed": true,
        "allow_separate_shipping_address": true,
        "color_button": "#FF9900",
        "color_button_text": "#FF9900",
        "color_checkbox": "#FF9900",
        "color_checkbox_checkmark": "#FF9900",
        "color_header": "#FF9900",
        "color_link": "#FF9900",
        "date_of_birth_mandatory": true,
        "shipping_details": "Delivered within 1-3 working days",
        "title_mandatory": true,
        "additional_checkbox": {
            "text": "Please add me to the newsletter list, read more here \link\",
            "checked": true,
            "required": true
        },
        "national_identification_number_mandatory": true,
        "additional_merchant_terms": "string",
        "phone_mandatory": true,
        "radius_border": "5",
        "allowed_customer_types": [
            "string"
        ],
        "show_subtotal_detail": true,
        "additional_checkboxes": 
            {
                "text": "Please add me to the newsletter list, read more here \[link\",
                "checked": true,
                "required": true,
                "id": "newsletter_opt_in"
            }
        ],
        "verify_national_identification_number": true,
        "enable_discount_module": true,
        "show_vat_registration_number_field": true
    },
    "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"
    },
    "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": true,
            "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\"}]}",
    "gui": {
        "options": [
            "string"
        ]
    },
    "merchant_requested": {
        "additional_checkbox": true,
        "additional_checkboxes": [
            {
                "id": "string",
                "checked": true
            }
        ]
    },
    "selected_shipping_option": {
        "id": "express_priority",
        "name": "EXPRESS 1-2 Days",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "preselected": true,
        "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": true,
    "recurring_token": "string",
    "recurring_description": "string",
    "billing_countries": [
        "string"
    ],
    "tags": [
        "string"
    ],
    "discount_lines": [
        {
            "name": "Super deal",
            "quantity": 5,
            "unit_price": -10000,
            "tax_rate": 1000,
            "total_amount": -2500,
            "total_tax_amount": -123,
            "reference": "645f54bb-dbb7-6e1f-83bd-bc81a2c3a258",
            "merchant_data": "{\"card_number\":\"5551234567890\"}"
        }
    ]
}

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
`{}`

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

Parameter	Description
Copy to share link to this field order_id string

Parameter

Description

order_id
string
read only

Unique order ID that will be used for the entire lifecycle of the order. (max 255 characters)

name
string
read only

The merchant name (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://docs.klarna.com/klarna-checkout/popular-use-cases/selling-to-multiple-countries/
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://docs.klarna.com/klarna-checkout/popular-use-cases/selling-to-multiple-countries/
Read more about data types

locale
string
required

Used to define the language and region of the customer. RFC 1766 customer's locale.
Read more about data types

status
string

The current status of the order. The status will be ‘incomplete’ until the customer has been successfully authorized.

billing_address
object

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

400	We were unable to update 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
`{}`
403	You tried to modify a read only resource. Show
`{}`
404	We did not find any order with given ID. You need to create a new order. Show
`{}`

Path:	POST /checkout/v3/orders
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 Rate Limiting

Rate Limit Information

Handling Rate limiting gracefully

Common causes, mitigation, and support

API Updates

Non-breaking changes

Guidelines

Checkout API

Order

Retrieve an order

HTTP Request

path collapse expand

Update an order

HTTP Request

body collapse expand

path collapse expand

Create a new order