load

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

load
Parameters
options (Object) An optional set of loading options
Name Description
options.setup Object A set of options to setup the flow. Same as the custom data attributes of the container element.
options.locale String The locale to control the language of the UI. Defaults to en . According to RFC 1766.
options.purchase_country String The purchase country, used to localize the experience. According to ISO 3166 alpha-2.
options.billing_countries Array<String> The billing countries, used to set allowed billing countries. According to ISO 3166 alpha-2.
options.purchase_currency String The purchase currency, used to properly format the prices. According to ISO 4217.
options.merchant_urls Object An object of merchant urls
options.order_lines Array<Object> An array of Order Lines
options.items Array<Object>? An array of Items, as all potential product variations
options.shipping_options Array<Object>? An array of Shipping Options
setup (Object) Setup information
Name Description
setup.key String The button key
setup.environment String? The environment to run against. Defaults to production . Use playground for testing purposes.
setup.region String? The region to run against. Defaults to eu . Use na for North America.
setup.instance_id String? If having multiple buttons per page use this value to target a specific button.
merchant_urls (Object) An object of merchant urls
Name Description
merchant_urls.terms String The URL of merchant terms and conditions.
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_line (Object) Order Line Item
Name Description
order_line.type String The order line type., e.g. physical
order_line.reference String The article number, SKU or similar.
order_line.name String The descriptive item name, maximum 255 characters.
order_line.quantity Object The Item quantity, non-negative, between 0 and 100000
order_line.unit_price Number The unit price including tax without applying discounts in minor units
order_line.tax_rate Number The number, two implicit decimals
order_line.total_amount Number The total amount includes tax and discount
order_line.total_discount_amount Number? The discount amount in minor units, includes tax
order_line.total_tax_amount Number The total tax amount in minor units
order_line.image_url String The URL to a product image
item (Object) Product Variation Item
Name Description
item.type String The order line type., e.g. physical
item.reference String? The article number, SKU or similar.
item.name String The descriptive item name, maximum 255 characters.
item.quantity Object? The Item quantity, non-negative, between 0 and 100000
item.unit_price Number The unit price including tax without applying discounts in minor units
item.tax_rate Number The number, two implicit decimals
item.total_amount Number? The total amount includes tax and discount
item.total_discount_amount Number? The discount amount in minor units, includes tax
item.total_tax_amount Number The total tax amount in minor units
item.image_url String? The URL to a product image
item.group_identifier String Unique identifier of the product that is described in multiple variations in this 'items' list.
item.product_attributes Array<Object> List of Product_Attributes objects, each describe every possible product variation as a unique combination of product attributes, e.g. color, size, material.
product_attribute (Object) Product_Attributes item
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
shipping_option (Object) Shipping Option Item
Name Description
shipping_option.id String The option id, e.g. express
shipping_option.name String The option name, e.g. EXPRESS 1-2 Days
shipping_option.description String The helpful text, e.g. Delivery by 4:30 pm
shipping_option.price Number The price including tax
shipping_option.tax_amount Number The tax amount
shipping_option.tax_rate Number The non-negative, in percent, two implicit decimals. i.e 2500 = 25%
shipping_option.promo String? The promotional text
shipping_option.preselected Boolean? The flag to influence preselection,
shipping_option.shipping_method String? One of PickUpStore | Home | BoxReg | BoxUnreg | PickUpPoint | Own
styling (Object) Styling Item
Name Description
styling.theme Object The theme Object
styling.theme.variation String Defines the colors of the button. One of 'klarna' | 'dark' | 'light'. Default is 'klarna'.
styling.theme.tagline String Defines the returning customer text color below the button. Can be either 'dark' or 'light'. Default is 'dark'.
styling.theme.type String Defines the type for the button. Each button type has different texts & adjustments. One of 'express' | 'buy' | 'pay'. Default is 'express'.
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 (Object) An optional set of options
Name Description
options.setup Object A set of options to target a specific button instance. Used in multiple buttons scenario.
setup (Object) Setup information
Name Description
setup.instance_id String If having multiple buttons per page use this value to target a specific button.
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 (Object) An optional set of options
Name Description
options.setup Object A set of options to target a specific button instance. Used in multiple buttons scenario.
setup (Object) Setup information
Name Description
setup.instance_id String If having multiple buttons per page use this value to target a specific button.
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.

open
Parameters
options (Object) An optional set of options to be used with open
setup (Object) Setup information
Name Description
setup.instance_id String? If having multiple buttons per page use this value to target a specific button.
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

Update the Instant Shopping flow.

update
Parameters
setup (Object) Setup information
Name Description
setup.instance_id String? If having multiple buttons per page use this value to target a specific button.
options (Object) An optional set of options to update
Name Description
options.setup Object A set of options to work with multiple buttons scenario.
options.locale string The locale to control the language of the UI. Defaults to en . According to RFC 1766.
options.purchase_country string The purchase country, used to localize the experience. According to ISO 3166 alpha-2.
options.billing_countries Array<String> The billing countries, used to set allowed billing countries. According to ISO 3166 alpha-2.
options.purchase_currency string The purchase currency, used to properly format the prices. According to ISO 4217.
options.merchant_urls Object? An object of merchant urls
options.order_lines Array<Object> An array of Order Lines
options.items Array<Object>? An array of Items, as all potential product variations
options.shipping_options Array<Object>? An array of Shipping Options
merchant_urls (Object?) An object of merchant urls
Name Description
merchant_urls.terms String? The URL of merchant terms and conditions.
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_line (Object) Order Line Item
Name Description
order_line.type String The order line type., e.g. physical
order_line.reference String The article number, SKU or similar.
order_line.name String The descriptive item name, maximum 255 characters.
order_line.quantity Object The Item quantity, non-negative, between 0 and 100000
order_line.unit_price Number The unit price including tax without applying discounts in minor units
order_line.tax_rate Number The number, two implicit decimals
order_line.total_amount Number The total amount includes tax and discount
order_line.total_discount_amount Number? The discount amount in minor units, includes tax
order_line.total_tax_amount Number? The total tax amount in minor units
order_line.image_url String The URL to a product image
item (Object) Product Variation Item
Name Description
item.type String The order line type., e.g. physical
item.reference String? The article number, SKU or similar.
item.name String The descriptive item name, maximum 255 characters.
item.quantity Object? The Item quantity, non-negative, between 0 and 100000
item.unit_price Number The unit price including tax without applying discounts in minor units
item.tax_rate Number The number, two implicit decimals
item.total_amount Number? The total amount includes tax and discount
item.total_discount_amount Number? The discount amount in minor units, includes tax
item.total_tax_amount Number The total tax amount in minor units
item.image_url String? The URL to a product image
item.group_identifier String Unique identifier of the product that is described in multiple variations in this 'items' list.
item.product_attributes Array<Object> List of Product_Attributes objects, each describe every possible product variation as a unique combination of product attributes, e.g. color, size, material.
shipping_option (Object) Shipping Option Item
Name Description
shipping_option.id String The option id, e.g. express
shipping_option.name String The option name, e.g. EXPRESS 1-2 Days
shipping_option.description String The helpful text, e.g. Delivery by 4:30 pm
shipping_option.price Number The price including tax
shipping_option.tax_amount Number The tax amount
shipping_option.tax_rate Number The non-negative, in percent, two implicit decimals. i.e 2500 = 25%
shipping_option.promo String? The promotional text
shipping_option.preselected Boolean? The flag to influence preselection,
shipping_option.shipping_method String? One of PickUpStore | Home | BoxReg | BoxUnreg | PickUpPoint | Own
styling (Object) Styling Item
Name Description
styling.theme Object The theme Object
styling.theme.variation String Defines the colors of the button. One of 'klarna' | 'dark' | 'light'. Default is 'klarna'.
styling.theme.tagline String Defines the returning customer text color below the button. Can be either 'dark' or 'light'. Default is 'dark'.
styling.theme.type String Defines the type for the button. Each button type has different texts & adjustments. One of 'express' | 'buy' | 'pay'. Default is 'express'.
callback (update~callback) A function to be called when the updating is completed.
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: { ... } }