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

The API is accessible through a few different URLS. There are different URLs for testing and for making live purchases as well as different URLs for depending on if you are based in Europe or in the U.S.

All interaction with Klarna's APIs must be done over HTTPS.

Live environment

The API for the European production environment can be found at

https://api.klarna.com/

The API for the U.S. production environment can be found at

https://api-na.klarna.com/

Testing environment

The API for the European testing environment can be found at

https://api.playground.klarna.com/

The API for the U.S. testing environment can be found at

https://api-na.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

{
  "error_code" : "ERROR_CODE",
  "error_messages" : ["Array of error messages"],
  "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.

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": "2015-11-29T10:25:40.000Z",
  "date_of_birth": "1981-09-06"
}

Dates are expressed according to the ISO 8601 standard with combined date, time and timezone. 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.

Checkout API

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

The Order object

JSON 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": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "shipping_address": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "order_amount": 50000,
    "order_tax_amount": 5000,
    "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": 5000,
            "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
            "product_url": "https://www.estore.com/products/f2a8d7e34",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "product_identifiers": {
                "category_path": "Electronics Store > Computers & Tablets > Desktops",
                "global_trade_item_number": "735858293167",
                "manufacturer_part_number": "BOXNUC5CPYH",
                "brand": "Intel"
            }
        }
    ],
    "customer": {
        "date_of_birth": "1995-10-20",
        "type": "person"
    },
    "merchant_urls": {
        "terms": "https://www.estore.com/terms.html",
        "cancellation_terms": "https://www.estore.com/terms/cancellation.html",
        "checkout": "https://www.estore.com/checkout.html",
        "confirmation": "https://www.estore.com/confirmation.html",
        "push": "https://www.estore.com/api/push",
        "validation": "https://www.estore.com/api/validation",
        "shipping_option_update": "https://www.estore.com/api/shipment",
        "address_update": "https://www.estore.com/api/address",
        "notification": "https://www.estore.com/api/pending",
        "country_change": "https://www.estore.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": "2018-04-23T10:40:18.040Z",
    "completed_at": "2018-04-23T10:40:18.040Z",
    "last_modified_at": "2018-04-23T10:40:18.040Z",
    "options": {
        "acquiring_channel": "eCommerce",
        "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",
            "checked": false,
            "required": false
        },
        "national_identification_number_mandatory": false,
        "radius_border": "5px",
        "allowed_customer_types": "[\"person\", \"company\"]",
        "show_subtotal_detail": false,
        "require_validate_callback_success": false
    },
    "attachment": {
        "content_type": "application/vnd.klarna.internal.emd-v2+json",
        "body": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}"
    },
    "external_payment_methods": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "external_checkouts": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "shipping_countries": [
        "us",
        "gb"
    ],
    "shipping_options": [
        {
            "id": "express_priority",
            "name": "EXPRESS 1-2 Days",
            "description": "Delivery by 4:30 pm",
            "promo": "Christmas Promotion",
            "price": 0,
            "tax_amount": 0,
            "tax_rate": 0,
            "preselected": false,
            "shipping_method": "PickUpStore"
        }
    ],
    "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
    "gui": {
        "options": [
            "disable_autofocus"
        ]
    },
    "merchant_requested": {
        "additional_checkbox": false
    },
    "selected_shipping_option": {
        "id": "express_priority",
        "name": "EXPRESS 1-2 Days",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "tax_amount": 0,
        "tax_rate": 0,
        "preselected": false,
        "shipping_method": "PickUpStore"
    }
}

Parameter

Description

order_id
string
read only

The unique order ID (max 255 characters).

name
string
read only

The merchant name (max 255 characters).

purchase_country
string
required

ISO 3166 alpha-2 purchase country.
Read more about data types

purchase_currency
string
required

ISO 4217 purchase currency.
Read more about data types

locale
string
required

RFC 1766 customer's locale.
Read more about data types

status
string
read only

The current status of the order.

billing_address
object

Once the customer has provided any data in the checkout iframe, updates to this object will be ignored (without generating an error).
Expand

Billing Address Object
Parameter	Description
Copy to share link to this field organization_name string
Copy to share link to this field reference string
Copy to share link to this field attention string
Copy to share link to this field given_name string	Given name.
Copy to share link to this field family_name string	Family name.
Copy to share link to this field email string	E-mail address.
Copy to share link to this field title string	Title. Valid values for UK: Mr Ms Mrs Miss Valid values for DACH: Herr Frau Valid values for NL: Dhr. Mevr.
Copy to share link to this field street_address string	Street address, first line.
Copy to share link to this field street_address2 string	Street address, second line.
Copy to share link to this field street_name string	Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
Copy to share link to this field street_number string	Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
Copy to share link to this field house_extension string	House extension. Only applicable in NL
Copy to share link to this field postal_code string	Postal/post code.
Copy to share link to this field city string	City.
Copy to share link to this field region string	State or Region.
Copy to share link to this field phone string	Phone number.
Copy to share link to this field country string	ISO 3166 alpha-2. Country. Read more about data types

shipping_address
object
read only

Unless the customer has explicitly chosen to enter a separate shipping address, this is a clone of billing_address.
Expand

Shipping Address Object
Parameter	Description
Copy to share link to this field organization_name string
Copy to share link to this field reference string
Copy to share link to this field attention string
Copy to share link to this field given_name string	Given name.
Copy to share link to this field family_name string	Family name.
Copy to share link to this field email string	E-mail address.
Copy to share link to this field title string	Title. Valid values for UK: Mr Ms Mrs Miss Valid values for DACH: Herr Frau Valid values for NL: Dhr. Mevr.
Copy to share link to this field street_address string	Street address, first line.
Copy to share link to this field street_address2 string	Street address, second line.
Copy to share link to this field street_name string	Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
Copy to share link to this field street_number string	Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
Copy to share link to this field house_extension string	House extension. Only applicable in NL
Copy to share link to this field postal_code string	Postal/post code.
Copy to share link to this field city string	City.
Copy to share link to this field region string	State or Region.
Copy to share link to this field phone string	Phone number.
Copy to share link to this field country string	ISO 3166 alpha-2. Country. Read more about data types

order_amount
integer
required

Non-negative, minor units. Total amount of the order, including tax and any discounts.

order_tax_amount
integer
required

Non-negative, minor units. The total tax amount of the order.

order_lines
array of order lines
required

The applicable order lines (max 1000)
Expand

Order Line Object

Parameter

Description

type
string

Order line type. Possible values:

physical
discount
shipping_fee
sales_tax
digital
gift_card
store_credit
surcharge

reference
string

Article number, SKU or similar.

name
string
required

Descriptive item name.

quantity
integer
required

Non-negative. The item quantity.

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)

tax_rate
integer
required

Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.

total_amount
integer
required

Includes tax and discount. Must match (quantity * unit_price) - total_discount_amount within ±quantity. (max value: 100000000)

total_discount_amount
integer

Non-negative minor units. Includes tax.

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

Pass through field. (max 255 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)

product_identifiers
object

Additional information identifying an item
Expand

Product Identifiers Object
Parameter	Description
Copy to share link to this field 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 ' > '
Copy to share link to this field 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
Copy to share link to this field 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
Copy to share link to this field 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.

customer
object

Information about the liable customer of the order.
Expand

Customer Object
Parameter	Description
Copy to share link to this field date_of_birth string	ISO 8601 date. The customer date of birth. Read more about data types
Copy to share link to this field type string	The default supported value is 'person'. If B2B is enabled for the merchant, the value may be "organization".

merchant_urls
object
required

The merchant_urls object.
Expand

Merchant Urls Object
Parameter	Description
Copy to share link to this field terms string required	URL of merchant terms and conditions. Should be different than checkout, confirmation and push URLs.(max 2000 characters)
Copy to share link to this field cancellation_terms string	URL of merchant cancellation terms.(max 2000 characters)
Copy to share link to this field checkout string required	URL of merchant checkout page. Should be different than terms, confirmation and push URLs. (max 2000 characters)
Copy to share link to this field confirmation string required	URL of merchant confirmation page. Should be different than checkout and confirmation URLs. (max 2000 characters)
Copy to share link to this field push string required	URL that will be requested when an order is completed. Should be different than checkout and confirmation URLs. (max 2000 characters)
Copy to share link to this field validation string	URL that will be requested for final merchant validation. (must be https, max 2000 characters)
Copy to share link to this field shipping_option_update string	URL for shipping option update. (must be https, max 2000 characters)
Copy to share link to this field address_update string	URL for shipping, tax and purchase currency updates. Will be called on address changes. (must be https, max 2000 characters)
Copy to share link to this field notification string	URL for notifications on pending orders. (max 2000 characters)
Copy to share link to this field country_change string	URL for shipping, tax and purchase currency updates. Will be called on purchase country changes. (must be https, max 2000 characters)

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" (max 255 characters).

merchant_reference2
string

Used for storing merchant's internal order number or other reference (max 255 characters).

started_at
string (datetime)
read only

ISO 8601 datetime. When the merchant created the order.
Read more about data types

completed_at
string (datetime)
read only

ISO 8601 datetime. When the customer completed the order.
Read more about data types

last_modified_at
string (datetime)
read only

ISO 8601 datetime. When the order was last modified.
Read more about data types

options
object

Options for this purchase.
Expand

Options Object

Parameter

Description

acquiring_channel
string

Acquiring channel for the order. Use MOTO for "Mail Order Telephone Order" or ECOMMERCE for "E-commerce". Default : ECOMMERCE

allow_separate_shipping_address
boolean

If true, the consumer can enter different billing and shipping addresses. Default: false

color_button
string

CSS hex color, e.g. "#FF9900"

color_button_text
string

CSS hex color, e.g. "#FF9900"

color_checkbox
string

CSS hex color, e.g. "#FF9900"

color_checkbox_checkmark
string

CSS hex color, e.g. "#FF9900"

color_header
string

CSS hex color, e.g. "#FF9900"

color_link
string

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

title_mandatory
boolean

If specified to false, title becomes optional. Only available for orders for country GB.

additional_checkbox
object
required

Additional merchant defined checkbox. e.g. for Newsletter opt-in.
Expand

Additional Checkbox Object
Parameter	Description
Copy to share link to this field text string required	Text that will be displayed to the consumer aside the checkbox. (max 255 characters)
Copy to share link to this field checked boolean required	Default state of the additional checkbox. It will use this value when loaded for the first time.
Copy to share link to this field 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

Additional merchant defined field. e.g. for purchases that MUST have a national insurance number.

radius_border
string

Border radius

allowed_customer_types
array of strings

A list of allowed customer types. Supported types: person & company.

show_subtotal_detail
boolean

If true, the Order Detail subtodals view is expanded. Default: false

require_validate_callback_success
boolean

If true, validate callback must get a positive response to not stop purchase. Default: false.

attachment
object

Additional purchase information required for some industries.
Expand

Attachment Object

Parameter

Description

content_type
string
required

The content type of the body property.

body
string
required

This field should be a string containing the body of the attachment. The body should be an object containing any of the keys and sub objects described below serialised to JSON.
Expand

Parameter

Description

air_reservation_details
array of air reservation detailss

Details about the reservation of airline tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	IATA Airport Code (three letters)
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	IATA Airport Code (three letters)
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	IATA Airline standard (two letters or digits)
Copy to share link to this field segment_price number	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of bus tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of train tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of ferry tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of hotel rooms
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

hotel_itinerary
array of hotel itinerarys

Hotel itinerary data, one per hotel stay
Expand

Parameter

Description

hotel_name
string

Name of hotel

address
object

Expand

Address Object
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 ids

Expand

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 insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of rental cars
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

car_rental_itinerary
array of car rental itinerarys

Car rental itinerary data
Expand

Parameter

Description

rental_company
string

Name of rental company

drivers_id
array of drivers ids

Expand

pick_up_location
object

Expand

Pick Up Location Object
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

drivers
array of driverss

Expand

Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field last_name string

affiliate_name
string

Name of the affiliate that originated the purchase. If none, leave blank.

event
array of events

Expand

Parameter

Description

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
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 vouchers

Expand

Parameter	Description
Copy to share link to this field voucher_name string	Description of the product the voucher entitles to, e.g. "China trip"
Copy to share link to this field 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."
Copy to share link to this field start_time string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field end_time string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field affiliate_name string	Name of the affiliate that originated the purchase. If none, leave blank.

subscription
array of subscriptions

Expand

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

marketplace_seller_info
array of marketplace seller infos

Expand

Parameter

Description

unique_account_identifier_seller
object

Expand

Unique Account Identifier Seller Object
Parameter	Description
Copy to share link to this field email string required
Copy to share link to this field pno string required
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field password string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field email string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field listing string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field login string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 infos

Expand

Parameter

Description

unique_account_identifier_winner
object

Expand

Unique Account Identifier Winner Object
Parameter	Description
Copy to share link to this field email string required
Copy to share link to this field pno string required
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field password string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field email string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field listing string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field login string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 infos

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field account_registration_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 fulls

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field payment_option string	card direct banking non klarna credit sms other
Copy to share link to this field number_paid_purchases integer	Total number of successful purchases
Copy to share link to this field total_amount_paid_purchases number	Total amount of successful purchases (local currency), e.g. 1234.00
Copy to share link to this field date_of_last_paid_purchase string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 simples

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field paid_before boolean	Whether the customer has paid before or not

other_delivery_address
array of other delivery addresss

Expand

Parameter	Description
Copy to share link to this field shipping_method undefined	store pick-up pick-up point registered box unregistered box
Copy to share link to this field shipping_type undefined	normal express
Copy to share link to this field first_name string
Copy to share link to this field last_name string
Copy to share link to this field street_address string
Copy to share link to this field street_number string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field country string

external_payment_methods
array of payment providers

List of external payment methods.
Expand

Payment Provider Object
Parameter	Description
Copy to share link to this field name string required	The name of the payment provider. (max 255 characters)
Copy to share link to this field redirect_url string required	URL to redirect to. (must be https, min 7, max 2000 characters)
Copy to share link to this field image_url string	URL to an image to display. (must be https, max 2000 characters)
Copy to share link to this field fee integer	Minor units. Includes tax.
Copy to share link to this field description string	Description. (max 500 characters)
Copy to share link to this field countries array of strings	If specified, limits the method to the listed countries (alpha 2 codes).

external_checkouts
array of payment providers

List of external checkouts.
Expand

Payment Provider Object
Parameter	Description
Copy to share link to this field name string required	The name of the payment provider. (max 255 characters)
Copy to share link to this field redirect_url string required	URL to redirect to. (must be https, min 7, max 2000 characters)
Copy to share link to this field image_url string	URL to an image to display. (must be https, max 2000 characters)
Copy to share link to this field fee integer	Minor units. Includes tax.
Copy to share link to this field description string	Description. (max 500 characters)
Copy to share link to this field countries array of strings	If specified, limits the method to the listed countries (alpha 2 codes).

shipping_countries
array of strings

A list of countries (ISO 3166 alpha-2). Default is purchase_country only.

shipping_options
array of shipping options

A list of shipping options available for this order.
Expand

Shipping Option Object
Parameter	Description
Copy to share link to this field id string required	id
Copy to share link to this field name string required	Name.
Copy to share link to this field description string	Description.
Copy to share link to this field promo string	Promotion name. To be used if this shipping option is promotional.
Copy to share link to this field price integer required	Price including tax.
Copy to share link to this field tax_amount integer required	Tax amount.
Copy to share link to this field tax_rate integer required	Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
Copy to share link to this field preselected boolean	If true, this option will be preselected when checkout loads. Default: false
Copy to share link to this field shipping_method string	Shipping method. Possible values: PickUpStore Home BoxReg BoxUnreg PickUpPoint Own

merchant_data
string

Pass through field (max 1024 characters).

gui
object

The gui object.
Expand

Gui Object
Parameter	Description
Copy to share link to this field options array of strings read only	An array of options to define the checkout behaviour. Supported options: disable_autofocus, minimal_confirmation.

merchant_requested
object
read only

Stores merchant requested data.
Expand

Merchant Requested Object
Parameter	Description
Copy to share link to this field additional_checkbox boolean read only	Informs whether the additional_checkbox is checked or not, when applicable.

selected_shipping_option
object
read only

Current shipping options selected by the customer.
Expand

Selected Shipping Option Object
Parameter	Description
Copy to share link to this field id string required	id
Copy to share link to this field name string required	Name.
Copy to share link to this field description string	Description.
Copy to share link to this field promo string	Promotion name. To be used if this shipping option is promotional.
Copy to share link to this field price integer required	Price including tax.
Copy to share link to this field tax_amount integer required	Tax amount.
Copy to share link to this field tax_rate integer required	Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
Copy to share link to this field preselected boolean	If true, this option will be preselected when checkout loads. Default: false
Copy to share link to this field shipping_method string	Shipping method. Possible values: PickUpStore Home BoxReg BoxUnreg PickUpPoint Own

Create a new order

Request

Path:	POST /checkout/v3/orders
Headers:	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": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "shipping_address": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "order_amount": 50000,
    "order_tax_amount": 5000,
    "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": 5000,
            "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
            "product_url": "https://www.estore.com/products/f2a8d7e34",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "product_identifiers": {
                "category_path": "Electronics Store > Computers & Tablets > Desktops",
                "global_trade_item_number": "735858293167",
                "manufacturer_part_number": "BOXNUC5CPYH",
                "brand": "Intel"
            }
        }
    ],
    "customer": {
        "date_of_birth": "1995-10-20",
        "type": "person"
    },
    "merchant_urls": {
        "terms": "https://www.estore.com/terms.html",
        "cancellation_terms": "https://www.estore.com/terms/cancellation.html",
        "checkout": "https://www.estore.com/checkout.html",
        "confirmation": "https://www.estore.com/confirmation.html",
        "push": "https://www.estore.com/api/push",
        "validation": "https://www.estore.com/api/validation",
        "shipping_option_update": "https://www.estore.com/api/shipment",
        "address_update": "https://www.estore.com/api/address",
        "notification": "https://www.estore.com/api/pending",
        "country_change": "https://www.estore.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": "2018-04-23T10:40:18.040Z",
    "completed_at": "2018-04-23T10:40:18.040Z",
    "last_modified_at": "2018-04-23T10:40:18.040Z",
    "options": {
        "acquiring_channel": "eCommerce",
        "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",
            "checked": false,
            "required": false
        },
        "national_identification_number_mandatory": false,
        "radius_border": "5px",
        "allowed_customer_types": "[\"person\", \"company\"]",
        "show_subtotal_detail": false,
        "require_validate_callback_success": false
    },
    "attachment": {
        "content_type": "application/vnd.klarna.internal.emd-v2+json",
        "body": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}"
    },
    "external_payment_methods": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "external_checkouts": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "shipping_countries": [
        "us",
        "gb"
    ],
    "shipping_options": [
        {
            "id": "express_priority",
            "name": "EXPRESS 1-2 Days",
            "description": "Delivery by 4:30 pm",
            "promo": "Christmas Promotion",
            "price": 0,
            "tax_amount": 0,
            "tax_rate": 0,
            "preselected": false,
            "shipping_method": "PickUpStore"
        }
    ],
    "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
    "gui": {
        "options": [
            "disable_autofocus"
        ]
    },
    "merchant_requested": {
        "additional_checkbox": false
    },
    "selected_shipping_option": {
        "id": "express_priority",
        "name": "EXPRESS 1-2 Days",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "tax_amount": 0,
        "tax_rate": 0,
        "preselected": false,
        "shipping_method": "PickUpStore"
    }
}

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": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "shipping_address": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "order_amount": 50000,
    "order_tax_amount": 5000,
    "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": 5000,
            "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
            "product_url": "https://www.estore.com/products/f2a8d7e34",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "product_identifiers": {
                "category_path": "Electronics Store > Computers & Tablets > Desktops",
                "global_trade_item_number": "735858293167",
                "manufacturer_part_number": "BOXNUC5CPYH",
                "brand": "Intel"
            }
        }
    ],
    "customer": {
        "date_of_birth": "1995-10-20",
        "type": "person"
    },
    "merchant_urls": {
        "terms": "https://www.estore.com/terms.html",
        "cancellation_terms": "https://www.estore.com/terms/cancellation.html",
        "checkout": "https://www.estore.com/checkout.html",
        "confirmation": "https://www.estore.com/confirmation.html",
        "push": "https://www.estore.com/api/push",
        "validation": "https://www.estore.com/api/validation",
        "shipping_option_update": "https://www.estore.com/api/shipment",
        "address_update": "https://www.estore.com/api/address",
        "notification": "https://www.estore.com/api/pending",
        "country_change": "https://www.estore.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": "2018-04-23T10:40:18.040Z",
    "completed_at": "2018-04-23T10:40:18.040Z",
    "last_modified_at": "2018-04-23T10:40:18.040Z",
    "options": {
        "acquiring_channel": "eCommerce",
        "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",
            "checked": false,
            "required": false
        },
        "national_identification_number_mandatory": false,
        "radius_border": "5px",
        "allowed_customer_types": "[\"person\", \"company\"]",
        "show_subtotal_detail": false,
        "require_validate_callback_success": false
    },
    "attachment": {
        "content_type": "application/vnd.klarna.internal.emd-v2+json",
        "body": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}"
    },
    "external_payment_methods": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "external_checkouts": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "shipping_countries": [
        "us",
        "gb"
    ],
    "shipping_options": [
        {
            "id": "express_priority",
            "name": "EXPRESS 1-2 Days",
            "description": "Delivery by 4:30 pm",
            "promo": "Christmas Promotion",
            "price": 0,
            "tax_amount": 0,
            "tax_rate": 0,
            "preselected": false,
            "shipping_method": "PickUpStore"
        }
    ],
    "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
    "gui": {
        "options": [
            "disable_autofocus"
        ]
    },
    "merchant_requested": {
        "additional_checkbox": false
    },
    "selected_shipping_option": {
        "id": "express_priority",
        "name": "EXPRESS 1-2 Days",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "tax_amount": 0,
        "tax_rate": 0,
        "preselected": false,
        "shipping_method": "PickUpStore"
    }
}

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.

HTTP Request

POST /checkout/v3/orders

Request parameters Response body

body collapse expand

Parameter

Description

order_id
string
read only

The unique order ID (max 255 characters).

name
string
read only

The merchant name (max 255 characters).

purchase_country
string
required

ISO 3166 alpha-2 purchase country.
Read more about data types

purchase_currency
string
required

ISO 4217 purchase currency.
Read more about data types

locale
string
required

RFC 1766 customer's locale.
Read more about data types

status
string
read only

The current status of the order.

billing_address
object

Once the customer has provided any data in the checkout iframe, updates to this object will be ignored (without generating an error).
Expand

Billing Address Object
Parameter	Description
Copy to share link to this field organization_name string
Copy to share link to this field reference string
Copy to share link to this field attention string
Copy to share link to this field given_name string	Given name.
Copy to share link to this field family_name string	Family name.
Copy to share link to this field email string	E-mail address.
Copy to share link to this field title string	Title. Valid values for UK: Mr Ms Mrs Miss Valid values for DACH: Herr Frau Valid values for NL: Dhr. Mevr.
Copy to share link to this field street_address string	Street address, first line.
Copy to share link to this field street_address2 string	Street address, second line.
Copy to share link to this field street_name string	Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
Copy to share link to this field street_number string	Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
Copy to share link to this field house_extension string	House extension. Only applicable in NL
Copy to share link to this field postal_code string	Postal/post code.
Copy to share link to this field city string	City.
Copy to share link to this field region string	State or Region.
Copy to share link to this field phone string	Phone number.
Copy to share link to this field country string	ISO 3166 alpha-2. Country. Read more about data types

shipping_address
object
read only

Unless the customer has explicitly chosen to enter a separate shipping address, this is a clone of billing_address.
Expand

Shipping Address Object
Parameter	Description
Copy to share link to this field organization_name string
Copy to share link to this field reference string
Copy to share link to this field attention string
Copy to share link to this field given_name string	Given name.
Copy to share link to this field family_name string	Family name.
Copy to share link to this field email string	E-mail address.
Copy to share link to this field title string	Title. Valid values for UK: Mr Ms Mrs Miss Valid values for DACH: Herr Frau Valid values for NL: Dhr. Mevr.
Copy to share link to this field street_address string	Street address, first line.
Copy to share link to this field street_address2 string	Street address, second line.
Copy to share link to this field street_name string	Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
Copy to share link to this field street_number string	Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
Copy to share link to this field house_extension string	House extension. Only applicable in NL
Copy to share link to this field postal_code string	Postal/post code.
Copy to share link to this field city string	City.
Copy to share link to this field region string	State or Region.
Copy to share link to this field phone string	Phone number.
Copy to share link to this field country string	ISO 3166 alpha-2. Country. Read more about data types

order_amount
integer
required

Non-negative, minor units. Total amount of the order, including tax and any discounts.

order_tax_amount
integer
required

Non-negative, minor units. The total tax amount of the order.

order_lines
array of order lines
required

The applicable order lines (max 1000)
Expand

Order Line Object

Parameter

Description

type
string

Order line type. Possible values:

physical
discount
shipping_fee
sales_tax
digital
gift_card
store_credit
surcharge

reference
string

Article number, SKU or similar.

name
string
required

Descriptive item name.

quantity
integer
required

Non-negative. The item quantity.

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)

tax_rate
integer
required

Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.

total_amount
integer
required

Includes tax and discount. Must match (quantity * unit_price) - total_discount_amount within ±quantity. (max value: 100000000)

total_discount_amount
integer

Non-negative minor units. Includes tax.

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

Pass through field. (max 255 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)

product_identifiers
object

Additional information identifying an item
Expand

Product Identifiers Object
Parameter	Description
Copy to share link to this field 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 ' > '
Copy to share link to this field 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
Copy to share link to this field 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
Copy to share link to this field 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.

customer
object

Information about the liable customer of the order.
Expand

Customer Object
Parameter	Description
Copy to share link to this field date_of_birth string	ISO 8601 date. The customer date of birth. Read more about data types
Copy to share link to this field type string	The default supported value is 'person'. If B2B is enabled for the merchant, the value may be "organization".

merchant_urls
object
required

The merchant_urls object.
Expand

Merchant Urls Object
Parameter	Description
Copy to share link to this field terms string required	URL of merchant terms and conditions. Should be different than checkout, confirmation and push URLs.(max 2000 characters)
Copy to share link to this field cancellation_terms string	URL of merchant cancellation terms.(max 2000 characters)
Copy to share link to this field checkout string required	URL of merchant checkout page. Should be different than terms, confirmation and push URLs. (max 2000 characters)
Copy to share link to this field confirmation string required	URL of merchant confirmation page. Should be different than checkout and confirmation URLs. (max 2000 characters)
Copy to share link to this field push string required	URL that will be requested when an order is completed. Should be different than checkout and confirmation URLs. (max 2000 characters)
Copy to share link to this field validation string	URL that will be requested for final merchant validation. (must be https, max 2000 characters)
Copy to share link to this field shipping_option_update string	URL for shipping option update. (must be https, max 2000 characters)
Copy to share link to this field address_update string	URL for shipping, tax and purchase currency updates. Will be called on address changes. (must be https, max 2000 characters)
Copy to share link to this field notification string	URL for notifications on pending orders. (max 2000 characters)
Copy to share link to this field country_change string	URL for shipping, tax and purchase currency updates. Will be called on purchase country changes. (must be https, max 2000 characters)

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" (max 255 characters).

merchant_reference2
string

Used for storing merchant's internal order number or other reference (max 255 characters).

started_at
string (datetime)
read only

ISO 8601 datetime. When the merchant created the order.
Read more about data types

completed_at
string (datetime)
read only

ISO 8601 datetime. When the customer completed the order.
Read more about data types

last_modified_at
string (datetime)
read only

ISO 8601 datetime. When the order was last modified.
Read more about data types

options
object

Options for this purchase.
Expand

Options Object

Parameter

Description

acquiring_channel
string

Acquiring channel for the order. Use MOTO for "Mail Order Telephone Order" or ECOMMERCE for "E-commerce". Default : ECOMMERCE

allow_separate_shipping_address
boolean

If true, the consumer can enter different billing and shipping addresses. Default: false

color_button
string

CSS hex color, e.g. "#FF9900"

color_button_text
string

CSS hex color, e.g. "#FF9900"

color_checkbox
string

CSS hex color, e.g. "#FF9900"

color_checkbox_checkmark
string

CSS hex color, e.g. "#FF9900"

color_header
string

CSS hex color, e.g. "#FF9900"

color_link
string

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

title_mandatory
boolean

If specified to false, title becomes optional. Only available for orders for country GB.

additional_checkbox
object
required

Additional merchant defined checkbox. e.g. for Newsletter opt-in.
Expand

Additional Checkbox Object
Parameter	Description
Copy to share link to this field text string required	Text that will be displayed to the consumer aside the checkbox. (max 255 characters)
Copy to share link to this field checked boolean required	Default state of the additional checkbox. It will use this value when loaded for the first time.
Copy to share link to this field 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

Additional merchant defined field. e.g. for purchases that MUST have a national insurance number.

radius_border
string

Border radius

allowed_customer_types
array of strings

A list of allowed customer types. Supported types: person & company.

show_subtotal_detail
boolean

If true, the Order Detail subtodals view is expanded. Default: false

require_validate_callback_success
boolean

If true, validate callback must get a positive response to not stop purchase. Default: false.

attachment
object

Additional purchase information required for some industries.
Expand

Attachment Object

Parameter

Description

content_type
string
required

The content type of the body property.

body
string
required

This field should be a string containing the body of the attachment. The body should be an object containing any of the keys and sub objects described below serialised to JSON.
Expand

Parameter

Description

air_reservation_details
array of air reservation detailss

Details about the reservation of airline tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	IATA Airport Code (three letters)
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	IATA Airport Code (three letters)
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	IATA Airline standard (two letters or digits)
Copy to share link to this field segment_price number	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of bus tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of train tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of ferry tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of hotel rooms
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

hotel_itinerary
array of hotel itinerarys

Hotel itinerary data, one per hotel stay
Expand

Parameter

Description

hotel_name
string

Name of hotel

address
object

Expand

Address Object
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 ids

Expand

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 insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of rental cars
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

car_rental_itinerary
array of car rental itinerarys

Car rental itinerary data
Expand

Parameter

Description

rental_company
string

Name of rental company

drivers_id
array of drivers ids

Expand

pick_up_location
object

Expand

Pick Up Location Object
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

drivers
array of driverss

Expand

Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field last_name string

affiliate_name
string

Name of the affiliate that originated the purchase. If none, leave blank.

event
array of events

Expand

Parameter

Description

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
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 vouchers

Expand

Parameter	Description
Copy to share link to this field voucher_name string	Description of the product the voucher entitles to, e.g. "China trip"
Copy to share link to this field 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."
Copy to share link to this field start_time string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field end_time string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field affiliate_name string	Name of the affiliate that originated the purchase. If none, leave blank.

subscription
array of subscriptions

Expand

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

marketplace_seller_info
array of marketplace seller infos

Expand

Parameter

Description

unique_account_identifier_seller
object

Expand

Unique Account Identifier Seller Object
Parameter	Description
Copy to share link to this field email string required
Copy to share link to this field pno string required
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field password string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field email string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field listing string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field login string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 infos

Expand

Parameter

Description

unique_account_identifier_winner
object

Expand

Unique Account Identifier Winner Object
Parameter	Description
Copy to share link to this field email string required
Copy to share link to this field pno string required
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field password string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field email string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field listing string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field login string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 infos

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field account_registration_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 fulls

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field payment_option string	card direct banking non klarna credit sms other
Copy to share link to this field number_paid_purchases integer	Total number of successful purchases
Copy to share link to this field total_amount_paid_purchases number	Total amount of successful purchases (local currency), e.g. 1234.00
Copy to share link to this field date_of_last_paid_purchase string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 simples

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field paid_before boolean	Whether the customer has paid before or not

other_delivery_address
array of other delivery addresss

Expand

Parameter	Description
Copy to share link to this field shipping_method undefined	store pick-up pick-up point registered box unregistered box
Copy to share link to this field shipping_type undefined	normal express
Copy to share link to this field first_name string
Copy to share link to this field last_name string
Copy to share link to this field street_address string
Copy to share link to this field street_number string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field country string

external_payment_methods
array of payment providers

List of external payment methods.
Expand

Payment Provider Object
Parameter	Description
Copy to share link to this field name string required	The name of the payment provider. (max 255 characters)
Copy to share link to this field redirect_url string required	URL to redirect to. (must be https, min 7, max 2000 characters)
Copy to share link to this field image_url string	URL to an image to display. (must be https, max 2000 characters)
Copy to share link to this field fee integer	Minor units. Includes tax.
Copy to share link to this field description string	Description. (max 500 characters)
Copy to share link to this field countries array of strings	If specified, limits the method to the listed countries (alpha 2 codes).

external_checkouts
array of payment providers

List of external checkouts.
Expand

Payment Provider Object
Parameter	Description
Copy to share link to this field name string required	The name of the payment provider. (max 255 characters)
Copy to share link to this field redirect_url string required	URL to redirect to. (must be https, min 7, max 2000 characters)
Copy to share link to this field image_url string	URL to an image to display. (must be https, max 2000 characters)
Copy to share link to this field fee integer	Minor units. Includes tax.
Copy to share link to this field description string	Description. (max 500 characters)
Copy to share link to this field countries array of strings	If specified, limits the method to the listed countries (alpha 2 codes).

shipping_countries
array of strings

A list of countries (ISO 3166 alpha-2). Default is purchase_country only.

shipping_options
array of shipping options

A list of shipping options available for this order.
Expand

Shipping Option Object
Parameter	Description
Copy to share link to this field id string required	id
Copy to share link to this field name string required	Name.
Copy to share link to this field description string	Description.
Copy to share link to this field promo string	Promotion name. To be used if this shipping option is promotional.
Copy to share link to this field price integer required	Price including tax.
Copy to share link to this field tax_amount integer required	Tax amount.
Copy to share link to this field tax_rate integer required	Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
Copy to share link to this field preselected boolean	If true, this option will be preselected when checkout loads. Default: false
Copy to share link to this field shipping_method string	Shipping method. Possible values: PickUpStore Home BoxReg BoxUnreg PickUpPoint Own

merchant_data
string

Pass through field (max 1024 characters).

gui
object

The gui object.
Expand

Gui Object
Parameter	Description
Copy to share link to this field options array of strings read only	An array of options to define the checkout behaviour. Supported options: disable_autofocus, minimal_confirmation.

merchant_requested
object
read only

Stores merchant requested data.
Expand

Merchant Requested Object
Parameter	Description
Copy to share link to this field additional_checkbox boolean read only	Informs whether the additional_checkbox is checked or not, when applicable.

selected_shipping_option
object
read only

Current shipping options selected by the customer.
Expand

Selected Shipping Option Object
Parameter	Description
Copy to share link to this field id string required	id
Copy to share link to this field name string required	Name.
Copy to share link to this field description string	Description.
Copy to share link to this field promo string	Promotion name. To be used if this shipping option is promotional.
Copy to share link to this field price integer required	Price including tax.
Copy to share link to this field tax_amount integer required	Tax amount.
Copy to share link to this field tax_rate integer required	Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
Copy to share link to this field preselected boolean	If true, this option will be preselected when checkout loads. Default: false
Copy to share link to this field shipping_method string	Shipping method. Possible values: PickUpStore Home BoxReg BoxUnreg PickUpPoint Own

Parameter

Description

order_id
string
read only

The unique order ID (max 255 characters).

name
string
read only

The merchant name (max 255 characters).

purchase_country
string
required

ISO 3166 alpha-2 purchase country.
Read more about data types

purchase_currency
string
required

ISO 4217 purchase currency.
Read more about data types

locale
string
required

RFC 1766 customer's locale.
Read more about data types

status
string
read only

The current status of the order.

billing_address
object

Once the customer has provided any data in the checkout iframe, updates to this object will be ignored (without generating an error).
Expand

Billing Address Object
Parameter	Description
Copy to share link to this field organization_name string
Copy to share link to this field reference string
Copy to share link to this field attention string
Copy to share link to this field given_name string	Given name.
Copy to share link to this field family_name string	Family name.
Copy to share link to this field email string	E-mail address.
Copy to share link to this field title string	Title. Valid values for UK: Mr Ms Mrs Miss Valid values for DACH: Herr Frau Valid values for NL: Dhr. Mevr.
Copy to share link to this field street_address string	Street address, first line.
Copy to share link to this field street_address2 string	Street address, second line.
Copy to share link to this field street_name string	Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
Copy to share link to this field street_number string	Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
Copy to share link to this field house_extension string	House extension. Only applicable in NL
Copy to share link to this field postal_code string	Postal/post code.
Copy to share link to this field city string	City.
Copy to share link to this field region string	State or Region.
Copy to share link to this field phone string	Phone number.
Copy to share link to this field country string	ISO 3166 alpha-2. Country. Read more about data types

shipping_address
object
read only

Unless the customer has explicitly chosen to enter a separate shipping address, this is a clone of billing_address.
Expand

Shipping Address Object
Parameter	Description
Copy to share link to this field organization_name string
Copy to share link to this field reference string
Copy to share link to this field attention string
Copy to share link to this field given_name string	Given name.
Copy to share link to this field family_name string	Family name.
Copy to share link to this field email string	E-mail address.
Copy to share link to this field title string	Title. Valid values for UK: Mr Ms Mrs Miss Valid values for DACH: Herr Frau Valid values for NL: Dhr. Mevr.
Copy to share link to this field street_address string	Street address, first line.
Copy to share link to this field street_address2 string	Street address, second line.
Copy to share link to this field street_name string	Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
Copy to share link to this field street_number string	Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
Copy to share link to this field house_extension string	House extension. Only applicable in NL
Copy to share link to this field postal_code string	Postal/post code.
Copy to share link to this field city string	City.
Copy to share link to this field region string	State or Region.
Copy to share link to this field phone string	Phone number.
Copy to share link to this field country string	ISO 3166 alpha-2. Country. Read more about data types

order_amount
integer
required

Non-negative, minor units. Total amount of the order, including tax and any discounts.

order_tax_amount
integer
required

Non-negative, minor units. The total tax amount of the order.

order_lines
array of order lines
required

The applicable order lines (max 1000)
Expand

Order Line Object

Parameter

Description

type
string

Order line type. Possible values:

physical
discount
shipping_fee
sales_tax
digital
gift_card
store_credit
surcharge

reference
string

Article number, SKU or similar.

name
string
required

Descriptive item name.

quantity
integer
required

Non-negative. The item quantity.

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)

tax_rate
integer
required

Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.

total_amount
integer
required

Includes tax and discount. Must match (quantity * unit_price) - total_discount_amount within ±quantity. (max value: 100000000)

total_discount_amount
integer

Non-negative minor units. Includes tax.

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

Pass through field. (max 255 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)

product_identifiers
object

Additional information identifying an item
Expand

Product Identifiers Object
Parameter	Description
Copy to share link to this field 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 ' > '
Copy to share link to this field 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
Copy to share link to this field 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
Copy to share link to this field 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.

customer
object

Information about the liable customer of the order.
Expand

Customer Object
Parameter	Description
Copy to share link to this field date_of_birth string	ISO 8601 date. The customer date of birth. Read more about data types
Copy to share link to this field type string	The default supported value is 'person'. If B2B is enabled for the merchant, the value may be "organization".

merchant_urls
object
required

The merchant_urls object.
Expand

Merchant Urls Object
Parameter	Description
Copy to share link to this field terms string required	URL of merchant terms and conditions. Should be different than checkout, confirmation and push URLs.(max 2000 characters)
Copy to share link to this field cancellation_terms string	URL of merchant cancellation terms.(max 2000 characters)
Copy to share link to this field checkout string required	URL of merchant checkout page. Should be different than terms, confirmation and push URLs. (max 2000 characters)
Copy to share link to this field confirmation string required	URL of merchant confirmation page. Should be different than checkout and confirmation URLs. (max 2000 characters)
Copy to share link to this field push string required	URL that will be requested when an order is completed. Should be different than checkout and confirmation URLs. (max 2000 characters)
Copy to share link to this field validation string	URL that will be requested for final merchant validation. (must be https, max 2000 characters)
Copy to share link to this field shipping_option_update string	URL for shipping option update. (must be https, max 2000 characters)
Copy to share link to this field address_update string	URL for shipping, tax and purchase currency updates. Will be called on address changes. (must be https, max 2000 characters)
Copy to share link to this field notification string	URL for notifications on pending orders. (max 2000 characters)
Copy to share link to this field country_change string	URL for shipping, tax and purchase currency updates. Will be called on purchase country changes. (must be https, max 2000 characters)

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" (max 255 characters).

merchant_reference2
string

Used for storing merchant's internal order number or other reference (max 255 characters).

started_at
string (datetime)
read only

ISO 8601 datetime. When the merchant created the order.
Read more about data types

completed_at
string (datetime)
read only

ISO 8601 datetime. When the customer completed the order.
Read more about data types

last_modified_at
string (datetime)
read only

ISO 8601 datetime. When the order was last modified.
Read more about data types

options
object

Options for this purchase.
Expand

Options Object

Parameter

Description

acquiring_channel
string

Acquiring channel for the order. Use MOTO for "Mail Order Telephone Order" or ECOMMERCE for "E-commerce". Default : ECOMMERCE

allow_separate_shipping_address
boolean

If true, the consumer can enter different billing and shipping addresses. Default: false

color_button
string

CSS hex color, e.g. "#FF9900"

color_button_text
string

CSS hex color, e.g. "#FF9900"

color_checkbox
string

CSS hex color, e.g. "#FF9900"

color_checkbox_checkmark
string

CSS hex color, e.g. "#FF9900"

color_header
string

CSS hex color, e.g. "#FF9900"

color_link
string

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

title_mandatory
boolean

If specified to false, title becomes optional. Only available for orders for country GB.

additional_checkbox
object
required

Additional merchant defined checkbox. e.g. for Newsletter opt-in.
Expand

Additional Checkbox Object
Parameter	Description
Copy to share link to this field text string required	Text that will be displayed to the consumer aside the checkbox. (max 255 characters)
Copy to share link to this field checked boolean required	Default state of the additional checkbox. It will use this value when loaded for the first time.
Copy to share link to this field 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

Additional merchant defined field. e.g. for purchases that MUST have a national insurance number.

radius_border
string

Border radius

allowed_customer_types
array of strings

A list of allowed customer types. Supported types: person & company.

show_subtotal_detail
boolean

If true, the Order Detail subtodals view is expanded. Default: false

require_validate_callback_success
boolean

If true, validate callback must get a positive response to not stop purchase. Default: false.

attachment
object

Additional purchase information required for some industries.
Expand

Attachment Object

Parameter

Description

content_type
string
required

The content type of the body property.

body
string
required

This field should be a string containing the body of the attachment. The body should be an object containing any of the keys and sub objects described below serialised to JSON.
Expand

Parameter

Description

air_reservation_details
array of air reservation detailss

Details about the reservation of airline tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	IATA Airport Code (three letters)
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	IATA Airport Code (three letters)
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	IATA Airline standard (two letters or digits)
Copy to share link to this field segment_price number	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of bus tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of train tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of ferry tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of hotel rooms
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

hotel_itinerary
array of hotel itinerarys

Hotel itinerary data, one per hotel stay
Expand

Parameter

Description

hotel_name
string

Name of hotel

address
object

Expand

Address Object
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 ids

Expand

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 insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of rental cars
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

car_rental_itinerary
array of car rental itinerarys

Car rental itinerary data
Expand

Parameter

Description

rental_company
string

Name of rental company

drivers_id
array of drivers ids

Expand

pick_up_location
object

Expand

Pick Up Location Object
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

drivers
array of driverss

Expand

Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field last_name string

affiliate_name
string

Name of the affiliate that originated the purchase. If none, leave blank.

event
array of events

Expand

Parameter

Description

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
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 vouchers

Expand

Parameter	Description
Copy to share link to this field voucher_name string	Description of the product the voucher entitles to, e.g. "China trip"
Copy to share link to this field 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."
Copy to share link to this field start_time string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field end_time string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field affiliate_name string	Name of the affiliate that originated the purchase. If none, leave blank.

subscription
array of subscriptions

Expand

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

marketplace_seller_info
array of marketplace seller infos

Expand

Parameter

Description

unique_account_identifier_seller
object

Expand

Unique Account Identifier Seller Object
Parameter	Description
Copy to share link to this field email string required
Copy to share link to this field pno string required
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field password string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field email string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field listing string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field login string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 infos

Expand

Parameter

Description

unique_account_identifier_winner
object

Expand

Unique Account Identifier Winner Object
Parameter	Description
Copy to share link to this field email string required
Copy to share link to this field pno string required
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field password string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field email string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field listing string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field login string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 infos

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field account_registration_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 fulls

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field payment_option string	card direct banking non klarna credit sms other
Copy to share link to this field number_paid_purchases integer	Total number of successful purchases
Copy to share link to this field total_amount_paid_purchases number	Total amount of successful purchases (local currency), e.g. 1234.00
Copy to share link to this field date_of_last_paid_purchase string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 simples

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field paid_before boolean	Whether the customer has paid before or not

other_delivery_address
array of other delivery addresss

Expand

Parameter	Description
Copy to share link to this field shipping_method undefined	store pick-up pick-up point registered box unregistered box
Copy to share link to this field shipping_type undefined	normal express
Copy to share link to this field first_name string
Copy to share link to this field last_name string
Copy to share link to this field street_address string
Copy to share link to this field street_number string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field country string

external_payment_methods
array of payment providers

List of external payment methods.
Expand

Payment Provider Object
Parameter	Description
Copy to share link to this field name string required	The name of the payment provider. (max 255 characters)
Copy to share link to this field redirect_url string required	URL to redirect to. (must be https, min 7, max 2000 characters)
Copy to share link to this field image_url string	URL to an image to display. (must be https, max 2000 characters)
Copy to share link to this field fee integer	Minor units. Includes tax.
Copy to share link to this field description string	Description. (max 500 characters)
Copy to share link to this field countries array of strings	If specified, limits the method to the listed countries (alpha 2 codes).

external_checkouts
array of payment providers

List of external checkouts.
Expand

Payment Provider Object
Parameter	Description
Copy to share link to this field name string required	The name of the payment provider. (max 255 characters)
Copy to share link to this field redirect_url string required	URL to redirect to. (must be https, min 7, max 2000 characters)
Copy to share link to this field image_url string	URL to an image to display. (must be https, max 2000 characters)
Copy to share link to this field fee integer	Minor units. Includes tax.
Copy to share link to this field description string	Description. (max 500 characters)
Copy to share link to this field countries array of strings	If specified, limits the method to the listed countries (alpha 2 codes).

shipping_countries
array of strings

A list of countries (ISO 3166 alpha-2). Default is purchase_country only.

shipping_options
array of shipping options

A list of shipping options available for this order.
Expand

Shipping Option Object
Parameter	Description
Copy to share link to this field id string required	id
Copy to share link to this field name string required	Name.
Copy to share link to this field description string	Description.
Copy to share link to this field promo string	Promotion name. To be used if this shipping option is promotional.
Copy to share link to this field price integer required	Price including tax.
Copy to share link to this field tax_amount integer required	Tax amount.
Copy to share link to this field tax_rate integer required	Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
Copy to share link to this field preselected boolean	If true, this option will be preselected when checkout loads. Default: false
Copy to share link to this field shipping_method string	Shipping method. Possible values: PickUpStore Home BoxReg BoxUnreg PickUpPoint Own

merchant_data
string

Pass through field (max 1024 characters).

gui
object

The gui object.
Expand

Gui Object
Parameter	Description
Copy to share link to this field options array of strings read only	An array of options to define the checkout behaviour. Supported options: disable_autofocus, minimal_confirmation.

merchant_requested
object
read only

Stores merchant requested data.
Expand

Merchant Requested Object
Parameter	Description
Copy to share link to this field additional_checkbox boolean read only	Informs whether the additional_checkbox is checked or not, when applicable.

selected_shipping_option
object
read only

Current shipping options selected by the customer.
Expand

Selected Shipping Option Object
Parameter	Description
Copy to share link to this field id string required	id
Copy to share link to this field name string required	Name.
Copy to share link to this field description string	Description.
Copy to share link to this field promo string	Promotion name. To be used if this shipping option is promotional.
Copy to share link to this field price integer required	Price including tax.
Copy to share link to this field tax_amount integer required	Tax amount.
Copy to share link to this field tax_rate integer required	Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
Copy to share link to this field preselected boolean	If true, this option will be preselected when checkout loads. Default: false
Copy to share link to this field shipping_method string	Shipping method. Possible values: PickUpStore Home BoxReg BoxUnreg PickUpPoint Own

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": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "shipping_address": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "order_amount": 50000,
    "order_tax_amount": 5000,
    "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": 5000,
            "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
            "product_url": "https://www.estore.com/products/f2a8d7e34",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "product_identifiers": {
                "category_path": "Electronics Store > Computers & Tablets > Desktops",
                "global_trade_item_number": "735858293167",
                "manufacturer_part_number": "BOXNUC5CPYH",
                "brand": "Intel"
            }
        }
    ],
    "customer": {
        "date_of_birth": "1995-10-20",
        "type": "person"
    },
    "merchant_urls": {
        "terms": "https://www.estore.com/terms.html",
        "cancellation_terms": "https://www.estore.com/terms/cancellation.html",
        "checkout": "https://www.estore.com/checkout.html",
        "confirmation": "https://www.estore.com/confirmation.html",
        "push": "https://www.estore.com/api/push",
        "validation": "https://www.estore.com/api/validation",
        "shipping_option_update": "https://www.estore.com/api/shipment",
        "address_update": "https://www.estore.com/api/address",
        "notification": "https://www.estore.com/api/pending",
        "country_change": "https://www.estore.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": "2018-04-23T10:40:18.040Z",
    "completed_at": "2018-04-23T10:40:18.040Z",
    "last_modified_at": "2018-04-23T10:40:18.040Z",
    "options": {
        "acquiring_channel": "eCommerce",
        "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",
            "checked": false,
            "required": false
        },
        "national_identification_number_mandatory": false,
        "radius_border": "5px",
        "allowed_customer_types": "[\"person\", \"company\"]",
        "show_subtotal_detail": false,
        "require_validate_callback_success": false
    },
    "attachment": {
        "content_type": "application/vnd.klarna.internal.emd-v2+json",
        "body": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}"
    },
    "external_payment_methods": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "external_checkouts": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "shipping_countries": [
        "us",
        "gb"
    ],
    "shipping_options": [
        {
            "id": "express_priority",
            "name": "EXPRESS 1-2 Days",
            "description": "Delivery by 4:30 pm",
            "promo": "Christmas Promotion",
            "price": 0,
            "tax_amount": 0,
            "tax_rate": 0,
            "preselected": false,
            "shipping_method": "PickUpStore"
        }
    ],
    "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
    "gui": {
        "options": [
            "disable_autofocus"
        ]
    },
    "merchant_requested": {
        "additional_checkbox": false
    },
    "selected_shipping_option": {
        "id": "express_priority",
        "name": "EXPRESS 1-2 Days",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "tax_amount": 0,
        "tax_rate": 0,
        "preselected": false,
        "shipping_method": "PickUpStore"
    }
}

401	You were not authorized to execute this operation. 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

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 required

Parameter

Description

order_id
string
read only

The unique order ID (max 255 characters).

name
string
read only

The merchant name (max 255 characters).

purchase_country
string
required

ISO 3166 alpha-2 purchase country.
Read more about data types

purchase_currency
string
required

ISO 4217 purchase currency.
Read more about data types

locale
string
required

RFC 1766 customer's locale.
Read more about data types

status
string
read only

The current status of the order.

billing_address
object

Once the customer has provided any data in the checkout iframe, updates to this object will be ignored (without generating an error).
Expand

Billing Address Object
Parameter	Description
Copy to share link to this field organization_name string
Copy to share link to this field reference string
Copy to share link to this field attention string
Copy to share link to this field given_name string	Given name.
Copy to share link to this field family_name string	Family name.
Copy to share link to this field email string	E-mail address.
Copy to share link to this field title string	Title. Valid values for UK: Mr Ms Mrs Miss Valid values for DACH: Herr Frau Valid values for NL: Dhr. Mevr.
Copy to share link to this field street_address string	Street address, first line.
Copy to share link to this field street_address2 string	Street address, second line.
Copy to share link to this field street_name string	Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
Copy to share link to this field street_number string	Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
Copy to share link to this field house_extension string	House extension. Only applicable in NL
Copy to share link to this field postal_code string	Postal/post code.
Copy to share link to this field city string	City.
Copy to share link to this field region string	State or Region.
Copy to share link to this field phone string	Phone number.
Copy to share link to this field country string	ISO 3166 alpha-2. Country. Read more about data types

shipping_address
object
read only

Unless the customer has explicitly chosen to enter a separate shipping address, this is a clone of billing_address.
Expand

Shipping Address Object
Parameter	Description
Copy to share link to this field organization_name string
Copy to share link to this field reference string
Copy to share link to this field attention string
Copy to share link to this field given_name string	Given name.
Copy to share link to this field family_name string	Family name.
Copy to share link to this field email string	E-mail address.
Copy to share link to this field title string	Title. Valid values for UK: Mr Ms Mrs Miss Valid values for DACH: Herr Frau Valid values for NL: Dhr. Mevr.
Copy to share link to this field street_address string	Street address, first line.
Copy to share link to this field street_address2 string	Street address, second line.
Copy to share link to this field street_name string	Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
Copy to share link to this field street_number string	Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
Copy to share link to this field house_extension string	House extension. Only applicable in NL
Copy to share link to this field postal_code string	Postal/post code.
Copy to share link to this field city string	City.
Copy to share link to this field region string	State or Region.
Copy to share link to this field phone string	Phone number.
Copy to share link to this field country string	ISO 3166 alpha-2. Country. Read more about data types

order_amount
integer
required

Non-negative, minor units. Total amount of the order, including tax and any discounts.

order_tax_amount
integer
required

Non-negative, minor units. The total tax amount of the order.

order_lines
array of order lines
required

The applicable order lines (max 1000)
Expand

Order Line Object

Parameter

Description

type
string

Order line type. Possible values:

physical
discount
shipping_fee
sales_tax
digital
gift_card
store_credit
surcharge

reference
string

Article number, SKU or similar.

name
string
required

Descriptive item name.

quantity
integer
required

Non-negative. The item quantity.

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)

tax_rate
integer
required

Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.

total_amount
integer
required

Includes tax and discount. Must match (quantity * unit_price) - total_discount_amount within ±quantity. (max value: 100000000)

total_discount_amount
integer

Non-negative minor units. Includes tax.

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

Pass through field. (max 255 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)

product_identifiers
object

Additional information identifying an item
Expand

Product Identifiers Object
Parameter	Description
Copy to share link to this field 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 ' > '
Copy to share link to this field 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
Copy to share link to this field 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
Copy to share link to this field 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.

customer
object

Information about the liable customer of the order.
Expand

Customer Object
Parameter	Description
Copy to share link to this field date_of_birth string	ISO 8601 date. The customer date of birth. Read more about data types
Copy to share link to this field type string	The default supported value is 'person'. If B2B is enabled for the merchant, the value may be "organization".

merchant_urls
object
required

The merchant_urls object.
Expand

Merchant Urls Object
Parameter	Description
Copy to share link to this field terms string required	URL of merchant terms and conditions. Should be different than checkout, confirmation and push URLs.(max 2000 characters)
Copy to share link to this field cancellation_terms string	URL of merchant cancellation terms.(max 2000 characters)
Copy to share link to this field checkout string required	URL of merchant checkout page. Should be different than terms, confirmation and push URLs. (max 2000 characters)
Copy to share link to this field confirmation string required	URL of merchant confirmation page. Should be different than checkout and confirmation URLs. (max 2000 characters)
Copy to share link to this field push string required	URL that will be requested when an order is completed. Should be different than checkout and confirmation URLs. (max 2000 characters)
Copy to share link to this field validation string	URL that will be requested for final merchant validation. (must be https, max 2000 characters)
Copy to share link to this field shipping_option_update string	URL for shipping option update. (must be https, max 2000 characters)
Copy to share link to this field address_update string	URL for shipping, tax and purchase currency updates. Will be called on address changes. (must be https, max 2000 characters)
Copy to share link to this field notification string	URL for notifications on pending orders. (max 2000 characters)
Copy to share link to this field country_change string	URL for shipping, tax and purchase currency updates. Will be called on purchase country changes. (must be https, max 2000 characters)

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" (max 255 characters).

merchant_reference2
string

Used for storing merchant's internal order number or other reference (max 255 characters).

started_at
string (datetime)
read only

ISO 8601 datetime. When the merchant created the order.
Read more about data types

completed_at
string (datetime)
read only

ISO 8601 datetime. When the customer completed the order.
Read more about data types

last_modified_at
string (datetime)
read only

ISO 8601 datetime. When the order was last modified.
Read more about data types

options
object

Options for this purchase.
Expand

Options Object

Parameter

Description

acquiring_channel
string

Acquiring channel for the order. Use MOTO for "Mail Order Telephone Order" or ECOMMERCE for "E-commerce". Default : ECOMMERCE

allow_separate_shipping_address
boolean

If true, the consumer can enter different billing and shipping addresses. Default: false

color_button
string

CSS hex color, e.g. "#FF9900"

color_button_text
string

CSS hex color, e.g. "#FF9900"

color_checkbox
string

CSS hex color, e.g. "#FF9900"

color_checkbox_checkmark
string

CSS hex color, e.g. "#FF9900"

color_header
string

CSS hex color, e.g. "#FF9900"

color_link
string

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

title_mandatory
boolean

If specified to false, title becomes optional. Only available for orders for country GB.

additional_checkbox
object
required

Additional merchant defined checkbox. e.g. for Newsletter opt-in.
Expand

Additional Checkbox Object
Parameter	Description
Copy to share link to this field text string required	Text that will be displayed to the consumer aside the checkbox. (max 255 characters)
Copy to share link to this field checked boolean required	Default state of the additional checkbox. It will use this value when loaded for the first time.
Copy to share link to this field 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

Additional merchant defined field. e.g. for purchases that MUST have a national insurance number.

radius_border
string

Border radius

allowed_customer_types
array of strings

A list of allowed customer types. Supported types: person & company.

show_subtotal_detail
boolean

If true, the Order Detail subtodals view is expanded. Default: false

require_validate_callback_success
boolean

If true, validate callback must get a positive response to not stop purchase. Default: false.

attachment
object

Additional purchase information required for some industries.
Expand

Attachment Object

Parameter

Description

content_type
string
required

The content type of the body property.

body
string
required

This field should be a string containing the body of the attachment. The body should be an object containing any of the keys and sub objects described below serialised to JSON.
Expand

Parameter

Description

air_reservation_details
array of air reservation detailss

Details about the reservation of airline tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	IATA Airport Code (three letters)
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	IATA Airport Code (three letters)
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	IATA Airline standard (two letters or digits)
Copy to share link to this field segment_price number	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of bus tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of train tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of ferry tickets
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

itinerary
array of itinerarys

Itinerary data, one per segment
Expand

Parameter	Description
Copy to share link to this field departure string	City code or name
Copy to share link to this field departure_city string
Copy to share link to this field arrival string	City code or name
Copy to share link to this field arrival_city string
Copy to share link to this field carrier string	Name of transportation company
Copy to share link to this field segment_price integer	Local currency
Copy to share link to this field departure_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field ticket_delivery_method undefined	pick_up email post phone
Copy to share link to this field 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.
Copy to share link to this field passenger_id array of passenger ids	Expand
Copy to share link to this field class string

insurance
array of insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of hotel rooms
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

hotel_itinerary
array of hotel itinerarys

Hotel itinerary data, one per hotel stay
Expand

Parameter

Description

hotel_name
string

Name of hotel

address
object

Expand

Address Object
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 ids

Expand

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 insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

passengers
array of persons

Passengers data
Expand

Person Object
Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field 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 detailss

Details about the reservation of rental cars
Expand

Parameter

Description

pnr
string

Trip booking number, e.g. VH67899

car_rental_itinerary
array of car rental itinerarys

Car rental itinerary data
Expand

Parameter

Description

rental_company
string

Name of rental company

drivers_id
array of drivers ids

Expand

pick_up_location
object

Expand

Pick Up Location Object
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 insurances

Insurance data
Expand

Parameter	Description
Copy to share link to this field insurance_company string
Copy to share link to this field insurance_type undefined	cancellation travel cancellation_travel bankruptcy
Copy to share link to this field insurance_price number	Local currency

drivers
array of driverss

Expand

Parameter	Description
Copy to share link to this field id integer
Copy to share link to this field title undefined	Mr, Mrs, Ms or blank if under 12 years mr mrs ms
Copy to share link to this field first_name string
Copy to share link to this field last_name string

affiliate_name
string

Name of the affiliate that originated the purchase. If none, leave blank.

event
array of events

Expand

Parameter

Description

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
Parameter	Description
Copy to share link to this field street_address string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field 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 vouchers

Expand

Parameter	Description
Copy to share link to this field voucher_name string	Description of the product the voucher entitles to, e.g. "China trip"
Copy to share link to this field 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."
Copy to share link to this field start_time string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field end_time string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field affiliate_name string	Name of the affiliate that originated the purchase. If none, leave blank.

subscription
array of subscriptions

Expand

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

marketplace_seller_info
array of marketplace seller infos

Expand

Parameter

Description

unique_account_identifier_seller
object

Expand

Unique Account Identifier Seller Object
Parameter	Description
Copy to share link to this field email string required
Copy to share link to this field pno string required
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field password string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field email string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field listing string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field login string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 infos

Expand

Parameter

Description

unique_account_identifier_winner
object

Expand

Unique Account Identifier Winner Object
Parameter	Description
Copy to share link to this field email string required
Copy to share link to this field pno string required
Copy to share link to this field 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
Parameter	Description
Copy to share link to this field password string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field email string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field listing string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field login string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 infos

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field account_registration_date string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 fulls

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field payment_option string	card direct banking non klarna credit sms other
Copy to share link to this field number_paid_purchases integer	Total number of successful purchases
Copy to share link to this field total_amount_paid_purchases number	Total amount of successful purchases (local currency), e.g. 1234.00
Copy to share link to this field date_of_last_paid_purchase string (datetime)	ISO 8601 e.g. 2012-11-24T15:00 Read more about data types
Copy to share link to this field 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 simples

Expand

Parameter	Description
Copy to share link to this field unique_account_identifier string	Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"
Copy to share link to this field paid_before boolean	Whether the customer has paid before or not

other_delivery_address
array of other delivery addresss

Expand

Parameter	Description
Copy to share link to this field shipping_method undefined	store pick-up pick-up point registered box unregistered box
Copy to share link to this field shipping_type undefined	normal express
Copy to share link to this field first_name string
Copy to share link to this field last_name string
Copy to share link to this field street_address string
Copy to share link to this field street_number string
Copy to share link to this field postal_code string
Copy to share link to this field city string
Copy to share link to this field country string

external_payment_methods
array of payment providers

List of external payment methods.
Expand

Payment Provider Object
Parameter	Description
Copy to share link to this field name string required	The name of the payment provider. (max 255 characters)
Copy to share link to this field redirect_url string required	URL to redirect to. (must be https, min 7, max 2000 characters)
Copy to share link to this field image_url string	URL to an image to display. (must be https, max 2000 characters)
Copy to share link to this field fee integer	Minor units. Includes tax.
Copy to share link to this field description string	Description. (max 500 characters)
Copy to share link to this field countries array of strings	If specified, limits the method to the listed countries (alpha 2 codes).

external_checkouts
array of payment providers

List of external checkouts.
Expand

Payment Provider Object
Parameter	Description
Copy to share link to this field name string required	The name of the payment provider. (max 255 characters)
Copy to share link to this field redirect_url string required	URL to redirect to. (must be https, min 7, max 2000 characters)
Copy to share link to this field image_url string	URL to an image to display. (must be https, max 2000 characters)
Copy to share link to this field fee integer	Minor units. Includes tax.
Copy to share link to this field description string	Description. (max 500 characters)
Copy to share link to this field countries array of strings	If specified, limits the method to the listed countries (alpha 2 codes).

shipping_countries
array of strings

A list of countries (ISO 3166 alpha-2). Default is purchase_country only.

shipping_options
array of shipping options

A list of shipping options available for this order.
Expand

Shipping Option Object
Parameter	Description
Copy to share link to this field id string required	id
Copy to share link to this field name string required	Name.
Copy to share link to this field description string	Description.
Copy to share link to this field promo string	Promotion name. To be used if this shipping option is promotional.
Copy to share link to this field price integer required	Price including tax.
Copy to share link to this field tax_amount integer required	Tax amount.
Copy to share link to this field tax_rate integer required	Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
Copy to share link to this field preselected boolean	If true, this option will be preselected when checkout loads. Default: false
Copy to share link to this field shipping_method string	Shipping method. Possible values: PickUpStore Home BoxReg BoxUnreg PickUpPoint Own

merchant_data
string

Pass through field (max 1024 characters).

gui
object

The gui object.
Expand

Gui Object
Parameter	Description
Copy to share link to this field options array of strings read only	An array of options to define the checkout behaviour. Supported options: disable_autofocus, minimal_confirmation.

merchant_requested
object
read only

Stores merchant requested data.
Expand

Merchant Requested Object
Parameter	Description
Copy to share link to this field additional_checkbox boolean read only	Informs whether the additional_checkbox is checked or not, when applicable.

selected_shipping_option
object
read only

Current shipping options selected by the customer.
Expand

Selected Shipping Option Object
Parameter	Description
Copy to share link to this field id string required	id
Copy to share link to this field name string required	Name.
Copy to share link to this field description string	Description.
Copy to share link to this field promo string	Promotion name. To be used if this shipping option is promotional.
Copy to share link to this field price integer required	Price including tax.
Copy to share link to this field tax_amount integer required	Tax amount.
Copy to share link to this field tax_rate integer required	Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
Copy to share link to this field preselected boolean	If true, this option will be preselected when checkout loads. Default: false
Copy to share link to this field shipping_method string	Shipping method. Possible values: PickUpStore Home BoxReg BoxUnreg PickUpPoint Own

Update an order

Request

Path:	POST /checkout/v3/orders/{order_id}
Headers:	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": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "shipping_address": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "order_amount": 50000,
    "order_tax_amount": 5000,
    "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": 5000,
            "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
            "product_url": "https://www.estore.com/products/f2a8d7e34",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "product_identifiers": {
                "category_path": "Electronics Store > Computers & Tablets > Desktops",
                "global_trade_item_number": "735858293167",
                "manufacturer_part_number": "BOXNUC5CPYH",
                "brand": "Intel"
            }
        }
    ],
    "customer": {
        "date_of_birth": "1995-10-20",
        "type": "person"
    },
    "merchant_urls": {
        "terms": "https://www.estore.com/terms.html",
        "cancellation_terms": "https://www.estore.com/terms/cancellation.html",
        "checkout": "https://www.estore.com/checkout.html",
        "confirmation": "https://www.estore.com/confirmation.html",
        "push": "https://www.estore.com/api/push",
        "validation": "https://www.estore.com/api/validation",
        "shipping_option_update": "https://www.estore.com/api/shipment",
        "address_update": "https://www.estore.com/api/address",
        "notification": "https://www.estore.com/api/pending",
        "country_change": "https://www.estore.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": "2018-04-23T10:40:18.040Z",
    "completed_at": "2018-04-23T10:40:18.040Z",
    "last_modified_at": "2018-04-23T10:40:18.040Z",
    "options": {
        "acquiring_channel": "eCommerce",
        "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",
            "checked": false,
            "required": false
        },
        "national_identification_number_mandatory": false,
        "radius_border": "5px",
        "allowed_customer_types": "[\"person\", \"company\"]",
        "show_subtotal_detail": false,
        "require_validate_callback_success": false
    },
    "attachment": {
        "content_type": "application/vnd.klarna.internal.emd-v2+json",
        "body": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}"
    },
    "external_payment_methods": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "external_checkouts": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "shipping_countries": [
        "us",
        "gb"
    ],
    "shipping_options": [
        {
            "id": "express_priority",
            "name": "EXPRESS 1-2 Days",
            "description": "Delivery by 4:30 pm",
            "promo": "Christmas Promotion",
            "price": 0,
            "tax_amount": 0,
            "tax_rate": 0,
            "preselected": false,
            "shipping_method": "PickUpStore"
        }
    ],
    "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
    "gui": {
        "options": [
            "disable_autofocus"
        ]
    },
    "merchant_requested": {
        "additional_checkbox": false
    },
    "selected_shipping_option": {
        "id": "express_priority",
        "name": "EXPRESS 1-2 Days",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "tax_amount": 0,
        "tax_rate": 0,
        "preselected": false,
        "shipping_method": "PickUpStore"
    }
}

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": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "shipping_address": {
        "organization_name": "string",
        "reference": "string",
        "attention": "string",
        "given_name": "John",
        "family_name": "Doe",
        "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"
    },
    "order_amount": 50000,
    "order_tax_amount": 5000,
    "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": 5000,
            "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
            "product_url": "https://www.estore.com/products/f2a8d7e34",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "product_identifiers": {
                "category_path": "Electronics Store > Computers & Tablets > Desktops",
                "global_trade_item_number": "735858293167",
                "manufacturer_part_number": "BOXNUC5CPYH",
                "brand": "Intel"
            }
        }
    ],
    "customer": {
        "date_of_birth": "1995-10-20",
        "type": "person"
    },
    "merchant_urls": {
        "terms": "https://www.estore.com/terms.html",
        "cancellation_terms": "https://www.estore.com/terms/cancellation.html",
        "checkout": "https://www.estore.com/checkout.html",
        "confirmation": "https://www.estore.com/confirmation.html",
        "push": "https://www.estore.com/api/push",
        "validation": "https://www.estore.com/api/validation",
        "shipping_option_update": "https://www.estore.com/api/shipment",
        "address_update": "https://www.estore.com/api/address",
        "notification": "https://www.estore.com/api/pending",
        "country_change": "https://www.estore.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": "2018-04-23T10:40:18.040Z",
    "completed_at": "2018-04-23T10:40:18.040Z",
    "last_modified_at": "2018-04-23T10:40:18.040Z",
    "options": {
        "acquiring_channel": "eCommerce",
        "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",
            "checked": false,
            "required": false
        },
        "national_identification_number_mandatory": false,
        "radius_border": "5px",
        "allowed_customer_types": "[\"person\", \"company\"]",
        "show_subtotal_detail": false,
        "require_validate_callback_success": false
    },
    "attachment": {
        "content_type": "application/vnd.klarna.internal.emd-v2+json",
        "body": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}"
    },
    "external_payment_methods": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "external_checkouts": [
        {
            "name": "PayhereUs",
            "redirect_url": "https://www.example.com/us/start",
            "image_url": "https://www.exampleobjects.com/logo.png",
            "fee": 0,
            "description": "an American company operating a worldwide online payments system",
            "countries": [
                "us",
                "gb"
            ]
        }
    ],
    "shipping_countries": [
        "us",
        "gb"
    ],
    "shipping_options": [
        {
            "id": "express_priority",
            "name": "EXPRESS 1-2 Days",
            "description": "Delivery by 4:30 pm",
            "promo": "Christmas Promotion",
            "price": 0,
            "tax_amount": 0,
            "tax_rate": 0,
            "preselected": false,
            "shipping_method": "PickUpStore"
        }
    ],
    "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
    "gui": {
        "options": [
            "disable_autofocus"
        ]
    },
    "merchant_requested": {
        "additional_checkbox": false
    },
    "selected_shipping_option": {
        "id": "express_priority",
        "name": "EXPRESS 1-2 Days",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "tax_amount": 0,
        "tax_rate": 0,
        "preselected": false,
        "shipping_method": "PickUpStore"
    }
}

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

Code Examples

To update an order simply provide a JSON object with the properties you want to update. Properties not provided in the request will stay the same.

Please note: an order can only be updated when the status is checkout_incomplete

HTTP Request

POST /checkout/v3/orders/{order_id}

Request parameters Response body

body collapse expand

Parameter

Description

order_id
string
read only

The unique order ID (max 255 characters).

name
string
read only

The merchant name (max 255 characters).

purchase_country
string
required

ISO 3166 alpha-2 purchase country.
Read more about data types

purchase_currency
string
required

ISO 4217 purchase currency.
Read more about data types

locale
string
required

RFC 1766 customer's locale.
Read more about data types

status
string
read only

The current status of the order.

billing_address
object

Once the customer has provided any data in the checkout iframe, updates to this object will be ignored (without generating an error).
Expand

Billing Address Object
Parameter	Description
Copy to share link to this field organization_name string
Copy to share link to this field reference string
Copy to share link to this field attention string
Copy to share link to this field given_name string	Given name.
Copy to share link to this field family_name string	Family name.
Copy to share link to this field email string	E-mail address.
Copy to share link to this field title string	Title. Valid values for UK: Mr Ms Mrs Miss Valid values for DACH: Herr Frau Valid values for NL: Dhr. Mevr.
Copy to share link to this field street_address string	Street address, first line.
Copy to share link to this field street_address2 string	Street address, second line.
Copy to share link to this field street_name string	Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
Copy to share link to this field street_number string	Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
Copy to share link to this field house_extension string	House extension. Only applicable in NL
Copy to share link to this field postal_code string	Postal/post code.
Copy to share link to this field city string	City.
Copy to share link to this field region string	State or Region.
Copy to share link to this field phone string	Phone number.
Copy to share link to this field country string	ISO 3166 alpha-2. Country. Read more about data types

shipping_address
object
read only

Unless the customer has explicitly chosen to enter a separate shipping address, this is a clone of billing_address.
Expand

Shipping Address Object
Parameter	Description
Copy to share link to this field organization_name string
Copy to share link to this field reference string
Copy to share link to this field attention string
Copy to share link to this field given_name string	Given name.
Copy to share link to this field family_name string	Family name.
Copy to share link to this field email string	E-mail address.
Copy to share link to this field title string	Title. Valid values for UK: Mr Ms Mrs Miss Valid values for DACH: Herr Frau Valid values for NL: Dhr. Mevr.
Copy to share link to this field street_address string	Street address, first line.
Copy to share link to this field street_address2 string	Street address, second line.
Copy to share link to this field street_name string	Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
Copy to share link to this field street_number string	Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
Copy to share link to this field house_extension string	House extension. Only applicable in NL
Copy to share link to this field postal_code string	Postal/post code.
Copy to share link to this field city string	City.
Copy to share link to this field region string	State or Region.
Copy to share link to this field phone string	Phone number.
Copy to share link to this field country string	ISO 3166 alpha-2. Country. Read more about data types

order_amount
integer
required

Non-negative, minor units. Total amount of the order, including tax and any discounts.

order_tax_amount
integer
required

Non-negative, minor units. The total tax amount of the order.

order_lines
array of order lines
required

The applicable order lines (max 1000)
Expand

Order Line Object

Parameter

Description

type
string

Order line type. Possible values:

physical
discount
shipping_fee
sales_tax
digital
gift_card
store_credit
surcharge

reference
string

Article number, SKU or similar.

name
string
required

Descriptive item name.

quantity
integer
required

Non-negative. The item quantity.

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)

tax_rate
integer
required

Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.

total_amount
integer
required

Includes tax and discount. Must match (quantity * unit_price) - total_discount_amount within ±quantity. (max value: 100000000)

total_discount_amount
integer

Non-negative minor units. Includes tax.

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

Pass through field. (max 255 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)

product_identifiers
object

Additional information identifying an item
Expand

Product Identifiers Object
Parameter	Description
Copy to share link to this field 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 ' > '
Copy to share link to this field 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
Copy to share link to this field 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
Copy to share link to this field 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.

customer
object

Information about the liable customer of the order.
Expand

Customer Object
Parameter	Description
Copy to share link to this field date_of_birth string	ISO 8601 date. The customer date of birth. Read more about data types
Copy to share link to this field type string	The default supported value is 'person'. If B2B is enabled for the merchant, the value may be "organization".

merchant_urls
object
required

The merchant_urls object.
Expand

Merchant Urls Object
Parameter	Description
Copy to share link to this field terms string required	URL of merchant terms and conditions. Should be different than checkout, confirmation and push URLs.(max 2000 characters)
Copy to share link to this field cancellation_terms string	URL of merchant cancellation terms.(max 2000 characters)
Copy to share link to this field checkout string required	URL of merchant checkout page. Should be different than terms, confirmation and push URLs. (max 2000 characters)
Copy to share link to this field confirmation string required	URL of merchant confirmation page. Should be different than checkout and confirmation URLs. (max 2000 characters)
Copy to share link to this field push string required	URL that will be requested when an order is completed. Should be different than checkout and confirmation URLs. (max 2000 characters)
Copy to share link to this field validation string	URL that will be requested for final merchant validation. (must be https, max 2000 characters)
Copy to share link to this field shipping_option_update string	URL for shipping option update. (must be https, max 2000 characters)
Copy to share link to this field address_update string	URL for shipping, tax and purchase currency updates. Will be called on address changes. (must be https, max 2000 characters)