InstantShopping~AdditionalCheckbox

InstantShopping~AdditionalCheckbox

Type: Object

Properties
id (String) : Unique id for the checkbox.
text (String) : Text that will be shown with checkbox.

InstantShopping~AllowEmpty

InstantShopping~AllowEmpty

Type: Object

Properties
order_lines (Boolean) : A property you can skip
items (Boolean) : A property you can skip

InstantShopping~Attachment

InstantShopping~Attachment

Type: Object

Properties
content_type (String) : The content type of the body property.
body (String) : 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.

InstantShopping~BillingAddress

InstantShopping~BillingAddress

Type: Object

Properties
given_name (String) : The first name of the consumer
family_name (String) : The family name of the consumer
title (String) : The personal title (UK to be one of ['Mr', 'Ms', 'Mrs', 'Miss'] | DACH to be one of ['Herr', 'Frau'] | NL to be one of [ 'Dhr.', 'Mevr'] )
email (String) : The email address of the consumer
street_address (String) : The first line of the street address of the consumer
street_address2 (String) : The second line of the street address of the consumer
postal_code (String) : The postal code of the address of the consumer
city (String) : The city from the address of the consumer
region (String) : The region from the address of the consumer
country (String) : The country from the address of the consumer. ISO 3166 alpha-2.
phone (String) : The phone number of the consumer

InstantShopping~ItemProductAttributeItem

InstantShopping~ItemProductAttributeItem

Type: Object

Properties
identifier (String) : Unique identifier of this attribute. E.g. 'clr_22' for a color attribute.
identifier_label (String) : This is a label that will be presented to the consumer when they will be asked to specify this attribute's value
value (String) : Unique identifier of the value of this product attribute
value_label (String) : The value presented to the consumer for selection for a specific product attribute

InstantShopping~ItemsItem

InstantShopping~ItemsItem

Type: Object

Properties
type (String) : The item type., e.g. physical
reference (String?) : The article number, SKU or similar.
name (String) : The descriptive item name, maximum 255 characters.
quantity (Number?) : The Item quantity, non-negative, between 0 and 100000
unit_price (Number) : The unit price including tax without applying discounts in minor units
tax_rate (Number) : The number, two implicit decimals
total_amount (Number?) : The total amount includes tax and discount
total_discount_amount (Number?) : The discount amount in minor units, includes tax
total_tax_amount (Number) : The total tax amount in minor units
image_url (String?) : The URL to a product image
product_identifiers (InstantShopping~ProductIdentifiers?) : Additional information identifying an item
shipping_attributes (InstantShopping~ShippingAttributes?) : The item shipping attributes
group_identifier (String) : Unique identifier of the product that is described in multiple variations in this 'items' list.
product_attributes (Array<InstantShopping~ItemProductAttributeItem>) : List of Product_Attributes objects, each describe every possible product variation as a unique combination of product attributes, e.g. color, size, material.

InstantShopping~LoadOptions

InstantShopping~LoadOptions

Type: Object

Properties
setup (InstantShopping~LoadSetupOptions) : A set of options to setup the flow. Same as the custom data attributes of the container element.
locale (String) : The locale to control the language of the UI. Defaults to en . According to RFC 1766.
purchase_country (String) : The purchase country, used to localize the experience. According to ISO 3166 alpha-2.
billing_countries (Array<String>) : The billing countries, used to set allowed billing countries. According to ISO 3166 alpha-2.
purchase_currency (String) : The purchase currency, used to properly format the prices. According to ISO 4217.
merchant_urls (InstantShopping~MerchantUrls) : An object of merchant urls*
attachment (InstantShopping~Attachment) : An object containing attachment definition. Additional purchase information required for some industries.*
billing_address (InstantShopping~BillingAddress?) : The billing address of the consumer, if known to the integrator
merchant_data (String?) : Pass through field
merchant_reference1 (String?) : Used for storing merchant's internal order number or other reference
merchant_reference2 (String?) : Used for storing merchant's internal order number or other reference
order_lines (Array<InstantShopping~OrderLinesItem>) : An array of Order Lines
items (Array<InstantShopping~ItemsItem>?) : An array of Items, as all potential product variations
shipping_options (Array<InstantShopping~ShippingOptionsItem>?) : An array of Shipping Options
styling (InstantShopping~StylingOptions?) : Styling options
shipping_attributes (InstantShopping~ShippingAttributes?) : The order's shipping attributes
validations (InstantShopping~Validations?) : Skip validations for given properties and render a disabled button
tokenization (InstantShopping~Tokenization?) : Button configuration for tokenization use-cases (eg subscriptions)
additional_checkboxes (Array<InstantShopping~AdditionalCheckbox>?) : Additional checkboxes that will be shown on the checkout page

InstantShopping~LoadSetupOptions

InstantShopping~LoadSetupOptions

Type: Object

Properties
key (String) : The button key
environment (String?) : The environment to run against. Defaults to production . Use playground for testing purposes.
region (String?) : The region to run against. Defaults to eu . Use na for North America.
instance_id (String?) : If having multiple buttons per page use this value to target a specific button.

InstantShopping~MerchantUrls

InstantShopping~MerchantUrls

Type: Object

Properties
terms (String) : The URL of merchant terms and conditions. Should be https.
confirmation (String?) : The URL of the post-purchase page to redirect the consumer to. Should be https.

InstantShopping~Options

InstantShopping~Options

Type: Object

Properties
setup (InstantShopping~SetupOptions) : Setup information

InstantShopping~OrderLinesItem

InstantShopping~OrderLinesItem

Type: Object

Properties
type (String) : The order line type., e.g. physical
reference (String) : The article number, SKU or similar.
name (String) : The descriptive item name, maximum 255 characters.
quantity (Number) : The Item quantity, non-negative, between 0 and 100000
unit_price (Number) : The unit price including tax without applying discounts in minor units
tax_rate (Number) : The number, two implicit decimals
total_amount (Number) : The total amount includes tax and discount
total_discount_amount (Number?) : The discount amount in minor units, includes tax
total_tax_amount (Number) : The total tax amount in minor units
image_url (String) : The URL to a product image
product_identifiers (InstantShopping~ProductIdentifiers?) : Additional information identifying an order line
shipping_attributes (InstantShopping~ShippingAttributes?) : The order line shipping attributes

InstantShopping~ProductIdentifiers

InstantShopping~ProductIdentifiers

Type: Object

Properties
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 ' > '
global_trade_item_number (String) : The product's Global Trade Item Number (GTIN). Common types of GTIN are EAN, ISBN or UPC. Exclude dashes and spaces, where possible
manufacturer_part_number (String) : The product's Manufacturer Part Number (MPN), which - together with the brand - uniquely identifies a product. Only submit MPNs assigned by a manufacturer and use the most specific MPN possible
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.

InstantShopping~SetupOptions

InstantShopping~SetupOptions

Type: Object

Properties
instance_id (String?) : If having multiple buttons per page use this value to target a specific button.

InstantShopping~ShippingAttributes

InstantShopping~ShippingAttributes

Type: Object

Properties
weight (Number) : The product's weight as used in the merchant's webshop. Non-negative. Measured in grams.
dimensions (InstantShopping~ShippingDimensions) : The product's dimensions: height, width and length. Of type Long.
tags (Array<String>) : The product's extra features.

InstantShopping~ShippingDeliveryDetailsPickupLocationAddress

InstantShopping~ShippingDeliveryDetailsPickupLocationAddress

Type: Object

Properties
street_address (String) : Street address, first line.
street_address2 (String) : Street address, second line.
postal_code (String) : Postal/post code.
city (String) : City.
region (String) : State or Region.
country (String) : ISO 3166 alpha-2. Country.

InstantShopping~ShippingDeliveryDetailsPickupLocation

InstantShopping~ShippingDeliveryDetailsPickupLocation

Type: Object

Properties
id (String) : Id
name (String) : Name of the location

InstantShopping~ShippingDeliveryDetailsProduct

InstantShopping~ShippingDeliveryDetailsProduct

Type: Object

Properties
name (String) : Carrier product name
identifier (String) : Carrier product identifier

InstantShopping~ShippingDeliveryDetailsTimeslot

InstantShopping~ShippingDeliveryDetailsTimeslot

Type: Object

Properties
id (String) : Id
start (String) : Start time.
end (String) : End time.

InstantShopping~ShippingDeliveryDetails

InstantShopping~ShippingDeliveryDetails

Type: Object

Properties
carrier (String) : Carrier product name
class (String) : Type of shipping class
product (InstantShopping~ShippingDeliveryDetailsProduct) : Upstream carrier product
pickup_location (InstantShopping~ShippingDeliveryDetailsPickupLocation) : The selected location for this shipping option
timeslot (InstantShopping~ShippingDeliveryDetailsTimeslot) : The selected timeslot for this shipping option

Properties
height (Number) : The product's height as used in the merchant's webshop. Non-negative. Measured in millimeters.
width (Number) : The product's width as used in the merchant's webshop. Non-negative. Measured in millimeters.
length (Number) : The product's length as used in the merchant's webshop. Non-negative. Measured in millimeters.

InstantShopping~ShippingOptionsItem

InstantShopping~ShippingOptionsItem

Type: Object

Properties
id (String) : The option id, e.g. express
name (String) : The option name, e.g. EXPRESS 1-2 Days
description (String) : The helpful text, e.g. Delivery by 4:30 pm
price (Number) : The price including tax
tax_amount (Number) : The tax amount
tax_rate (Number) : The non-negative, in percent, two implicit decimals. i.e 2500 = 25%
promo (String?) : The promotional text
preselected (Boolean?) : The flag to influence preselection,
shipping_method (String?) : One of PickUpStore | Home | BoxReg | BoxUnreg | PickUpPoint | Own
delivery_details (InstantShopping~ShippingDeliveryDetails?) : The delivery details for this shipping option

InstantShopping~StylingOptionsTheme

InstantShopping~StylingOptionsTheme

Type: Object

Properties
variation (String) : Defines the colors of the button. One of 'klarna' | 'dark' | 'light'. Default is 'klarna'.
type (String) : Defines the type for the button. Each button type has different texts & adjustments. One of 'express' | 'buy' | 'pay' | 'click_and_collect' | 'donation'. Default is 'express'.

InstantShopping~StylingOptions

InstantShopping~StylingOptions

Type: Object

Properties
theme (InstantShopping~StylingOptionsTheme) : Defines the specifics of the desired theme

InstantShopping~Tokenization

InstantShopping~Tokenization

Type: Object

Properties
description (String) : Legal text, describing the conditions of this subscription.
free_trial_days (Number?) : if the subscription includes a free-trial period, specify the amount of days. This will help us make it clear to the consumer that for the current purchase no money will be deducted.

InstantShopping~UpdateOptions

InstantShopping~UpdateOptions

Type: Object

Properties
setup (InstantShopping~SetupOptions) : A set of options to setup the flow. Same as the custom data attributes of the container element.
locale (String) : The locale to control the language of the UI. Defaults to en . According to RFC 1766.
purchase_country (String) : The purchase country, used to localize the experience. According to ISO 3166 alpha-2.
billing_countries (Array<String>) : The billing countries, used to set allowed billing countries. According to ISO 3166 alpha-2.
purchase_currency (String) : The purchase currency, used to properly format the prices. According to ISO 4217.
merchant_urls (InstantShopping~MerchantUrls) : An object of merchant urls*
attachment (InstantShopping~Attachment) : An object containing attachment definition. Additional purchase information required for some industries.*
billing_address (InstantShopping~BillingAddress?) : The billing address of the consumer, if known to the integrator
merchant_data (String?) : Pass through field
merchant_reference1 (String?) : Used for storing merchant's internal order number or other reference
merchant_reference2 (String?) : Used for storing merchant's internal order number or other reference
order_lines (Array<InstantShopping~OrderLinesItem>) : An array of Order Lines
items (Array<InstantShopping~ItemsItem>?) : An array of Items, as all potential product variations
shipping_options (Array<InstantShopping~ShippingOptionsItem>?) : An array of Shipping Options
styling (InstantShopping~StylingOptions?) : Styling options
shipping_attributes (InstantShopping~ShippingAttributes?) : The order's shipping attributes
validations (InstantShopping~Validations?) : Skip validations for given properties and render a disabled button
additional_checkboxes (Array<InstantShopping~AdditionalCheckbox>?) : Additional checkboxes that will be shown on the checkout page

InstantShopping~Validations

InstantShopping~Validations

Type: Object

Properties
allow_empty (InstantShopping~AllowEmpty) : The object containing the properties to skip validations for

load

Load the Instant Shopping flow. Accepts setup options according to the schema and configures the button.

load
Parameters
options (InstantShopping~LoadOptions) An optional set of loading options
callback (load~callback) A function to be called when the loading is completed.
Throws
  • ApplicationNotLoadedError: If the application fails to load due to iframe not being created.
  • InvalidButtonOptionsError: If the button key is missing
  • InvalidConfigurationError: when dataset configuration is missing or is not valid
  • MissingContainerError: when the Instant Shopping button needs to render but no container element is defined or can be found
Example
try {
  Klarna.InstantShopping.load({}, function (callbackData) { console.log('Smoooth!') })
} catch (e) {
  // Handle the error
}

load~callback

Called with the result of the load operation.

load~callback
Parameters
res (Object) Response
Name Description
res.show_button Boolean A boolean indicating the result of the button loading.
res.error Object Only available in case of solvable errors.
Example
Successful -> { show_button: true }
Failed -> { show_button: false, error: { ... } }

off

Unregisters an event handler for the given eventName.

off
Parameters
eventName (String) The name of the event from which you want to unsubscribe.
eventHandler (off~eventHandler?) The function that was previously registered for the eventName . Omit if you want to unregister all handlers for the eventName .
options (InstantShopping~Options) An optional set of options
Example
var theEventHandler = function () { ... }
Klarna.InstantShopping.on('confirmation_displayed', theEventHandler)

// unregister this specific listener for confirmation_displayed
Klarna.InstantShopping.off('confirmation_displayed', theEventHandler)

// unregister _all_ listeners for confirmation_displayed
Klarna.InstantShopping.off('confirmation_displayed')

// Multiple buttons scenario: unregister _all_ listeners for confirmation_displayed for instance_id 'button-instance-6a2a0390'
Klarna.InstantShopping.off('confirmation_displayed', undefined, {setup: {instance_id: 'button-instance-6a2a0390'}})

on

Registers an event handler for the given eventName. The events are triggered internally in Klarna InstantShopping. The supported events are:

  • buy_button_clicked: Emitted when the buy button is clicked. The registered event handler is called with callback data.
  • session_initiated: Emitted when the session is initiated (on response from /create-session). The registered event handler is called with callback data that includes the property customer_country, customer_region, customer_postal_code from billing address.
  • instant_shopping_flow_opened: Emitted when the instant shopping flow is opened (fullscreen dialog is shown). The registered event handler is called with callback data.
  • instant_shopping_flow_closed: Emitted when the instant shopping flow is closed (fullscreen dialog is shut down). The registered event handler is called with callback data that includes the property from which is the view that was showing before closing. This may be specification, identification, checkout, shipping, payment, error.
  • identification_updated: Emitted when identification information is added/updated. (on response from identification/reload). The registered event handler is called with callback data that includes the property customer_country, customer_region, customer_postal_code from billing address.
  • shipping_updated: Emitted when shipping information is added/updated. (on response from shipping/reload). The registered event handler is called with callback data that includes the property customer_selected_shipping_option, customer_country, customer_region, customer_postal_code from shipping address.
  • product_specifications_selected: Emitted when product specifications are selected. (on response specifications/selected). The registered event handler is called with callback data that includes the property customer_order_lines, customer_order_amount, customer_order_tax_amount from order.
  • complete_order_button_clicked: Emitted when the complete order button is clicked. The registered event handler is called with callback data.
  • confirmation_displayed: Emitted when the confirmation is shown. The registered event handler is called with callback data. Additionally order_id is provided.
  • confirmation_button_clicked: Emitted when the customer clicks on the call to action from the confirmation view after a successful purchase. Clicking on this either shuts down the Instant Shopping flow or redirects the customer to a post-purchase page defined when setting up the button key.
on
Parameters
eventName (String) The name of the event to which you want to subscribe.
eventHandler (on~eventHandler) The function that should be called when the event is emitted.
options (InstantShopping~Options) An optional set of options
Throws
  • EventNotSupportedError: If trying to register an unsupported event.
Example
// register on confirmation_displayed event
Klarna.InstantShopping.on('confirmation_displayed', function () {
  console.log('The smoooth confirmation view is displayed.')
})

// Multiple buttons scenario: register on buy_button_clicked for button with instance_id 'button-instance-6a2a0390'
Klarna.InstantShopping.on('buy_button_clicked', function () {
  console.log('The smoooth buy button was clicked. This is event added to button-instance-6a2a0390 only')
}, {setup: {instance_id: 'button-instance-6a2a0390'}})

on~eventHandler

Called whenever the associated event is emitted inside Klarna InstantShopping.

on~eventHandler(key: any, environment: any, region: any, context_id: any, session_id: any, integrator_url: any, instance_id: any): any
Parameters
key (any) The button key.
environment (any) The environment. Currently supporting playground and production.
region (any) The region. Currently supporting eu and na.
context_id (any) Uuid representing the instant shopping flow.
session_id (any) Uuid representing the session. This id is valid until a purchase is completed.
integrator_url (any) The integration url.
instance_id (any) The instance_id for the button.
Returns
any: undefined

open

Open the Instant Shopping flow. It accepts a callback to notify that the flow has opened or has failed to open. Make sure that Instant shopping load has been executed before calling open.

open
Parameters
options (InstantShopping~Options) An optional set of options to be used with open
callback (open~callback) A function to be called when the opening of the modal is completed.
Throws
  • ApplicationNotLoadedError: If the application is not properly loaded and no iframe is found.
Example
try {
  Klarna.InstantShopping.open()
} catch (e) {
  // Handle the error
}

open~callback

Called with the result of the open operation.

open~callback
Parameters
res (Object) Response
Name Description
res.show_fullscreen Boolean A boolean indicating the result of the modal opening.
res.error Object Only available in case of solvable errors.
Example
Successful -> { show_fullscreen: true }
Failed -> { show_fullscreen: false, error: { ... } }

update

Updates the Instant Shopping flow. Accepts setup options according to the schema and configures the button. Make sure that Instant shopping load has been executed before calling update.

update
Parameters
options (InstantShopping~UpdateOptions) An optional set of loading options
callback (update~callback) A function to be called when the updating is completed. BB
Throws
  • ApplicationNotLoadedError: If the application is not properly loaded and no iframe is found.
  • ApplicationNotUpdatedError: If there has been a problem applying the updated options.
Example
try {
  Klarna.InstantShopping.update()
} catch (e) {
  // Handle the error
}

update~callback

Called with the result of the update operation.

update~callback
Parameters
res (Object) Response
Name Description
res.show_button Boolean A boolean indicating the result of the button updating.
res.error Object Only available in case of solvable errors.
Example
Successful -> { show_button: true }
Failed -> { show_button: false, error: { ... } }

updateContext

Clear context if app ID has changed

updateContext
Parameters
instanceId (any)
context (any)
updateOptions (any)
Returns
any: context