Additional Features

Choose between Klarna themes

It is possible to setup an Instant Shopping button and choose between different Klarna themes. We currently support the fully Klarna branded theme, as well as some lower branded themes in dark and light mode. To set this up you can pass the configuration below either when creating a new button key through the Button Key Generation API, or when configuring a specific Instant Shopping flow through the JavaScript API load.

Example of specifying the light Klarna theme through the JavaScript API. It is assumed that you probably have a dark background to your pages.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
  <script>
    window.klarnaAsyncCallback = function () {
      Klarna.InstantShopping.load({
        // setup options here
        "styling": {
          "theme" : {
            "variation": "light",
            "tagline": "light"
          }
        }
      })
    }
  </script>
}

Klarna light theme

Example of specifying the dark Klarna theme through the JavaScript API.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
  <script>
    window.klarnaAsyncCallback = function () {
      Klarna.InstantShopping.load({
        // setup options here
        "styling": {
          "theme" : {
            "variation": "dark",
            "tagline": "dark"
          }
        }
      })
    }
  </script>
}

Klarna light theme

Example of specifying the default Klarna theme, but the light tagline through the JavaScript API. It is assumed that you probably have a dark background to your pages.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
  <script>
    window.klarnaAsyncCallback = function () {
      Klarna.InstantShopping.load({
        // setup options here
        "styling": {
          "theme" : {
            "variation": "klarna",
            "tagline": "light"
          }
        }
      })
    }
  </script>
}

Klarna light theme

Choose between button types

There are predefined types of buttons differing in text & branding. We currently support button type express, buy & pay. Here’s an example using button type express:

1
2
3
4
5
6
7
8
9
10
11
12
<script>
  window.klarnaAsyncCallback = function () {
    Klarna.InstantShopping.load({
      // setup options here
      "styling": {
        "theme": {
          "type": "express"
        }
      }
    })
  }
</script>

Button type express

…and here’s an example using button type buy:

1
2
3
4
5
6
7
8
9
10
11
12
<script>
  window.klarnaAsyncCallback = function () {
    Klarna.InstantShopping.load({
      // setup options here
      "styling": {
        "theme": {
          "type": "buy"
        }
      }
    })
  }
</script>

Button type buy

…and lastly, here’s an example using button type pay:

1
2
3
4
5
6
7
8
9
10
11
12
<script>
  window.klarnaAsyncCallback = function () {
    Klarna.InstantShopping.load({
      // setup options here
      "styling": {
        "theme": {
          "type": "pay"
        }
      }
    })
  }
</script>

Button type pay

Direct distribution links for Button Keys suitable for offsite

When you create a button key suitable for offsite usage (i.e. contains order_lines or items) you will see two distribution links in the button key data:

1
2
3
4
5
6
7
8
9
10
11
12
  {
    "links": [
      {
        "rel":"hosted_page_url",
        "href":"https://pop.klarna.com/kis-123e4567-e89b-12d3-a456-426655440000"
      },
      {
        "rel":"hosted_page_qrcode",
        "href":"https://pop.klarna.com/kis-123e4567-e89b-12d3-a456-426655440000/qr"
      }
    ]
  }

The first link, identified by hosted_page_url, will get you to a page hosted by Klarna, where your customers can buy using Instant Shopping. The second link, identified by hosted_page_qrcode, will get you to a page where you can print the QRcode of that first link. Scanning this QR code will redirect to a hosted Instant Shopping page, where your customer can complete a purchase in seconds, taking advantage of the Klarna cookie stored in their device. A recommended use of these links is for offline campaigns and/or selling online when you do not necessary need to own the webpage and UI.

If you are interested to know when the customer has arrived to certain steps during the Instant Shopping purchase flow you can take advantage of the events emitted. The supported events are:

buy_button_clicked: Emitted when the Instant Shopping button is clicked.
session_initiated: Emitted when the session is initiated (on response from /create-session). Callback base data is extended with customer_country, customer_region, customer_postal_code from billing address.
instant_shopping_flow_opened: Emitted when the Instant Shopping flow is opened.
instant_shopping_flow_closed: Emitted when the Instant Shopping flow is closed.
identification_updated: Emitted when identification information is added/updated. (on response from identification/reload). Callback base data is extended with customer_country, customer_region, customer_postal_code from billing address.
shipping_updated: Emitted when shipping information is added/updated. (on response from shipping/reload). Callback base data is extended with 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). Callback base data is extended with customer_order_lines, customer_order_amount, customer_order_tax_amount from order.
complete_order_button_clicked: Emitted when the customer clicks to complete order from inside the Instant Shopping flow.
confirmation_displayed: Emitted when the confirmation view is shown, after a successful pruchase. Callback base data is extended with order_id.
confirmation_button_clicked: Emitted when the call to action from the confirmation view is clicked. Clicking this with either follow the redirect to merchant_urls.confirmation or merely shut down our view.

Callback base data is included in supported events:

key: the button key;
environment: the environment, will be playground in testing mode;
region: the region, will be eu for Europe or na for North America region;
context_id: a unique id for distinguishing the customer flows for purchasing different products on different pages;
session_id: a unique id for distinguishing the customer flow for purchasing a specific product;
integrator_url: the url of the page that is including this Instant Shopping button.

To start listening to an event, you can use the JavaScript API on, as shown in the example below:

1
2
3
  Klarna.InstantShopping.on('confirmation_displayed', function (callbackData) {
    console.log('The smoooth confirmation view is displayed. Order Id', callbackData.order_id)
  })

To stop listening to an event, you again use the JavaScript API off, as shown in the example below:

1
  Klarna.InstantShopping.off('confirmation_displayed')

More detailed information can be found in the JavaScript API documentation .

Programmatically open up the Instant Shopping flow

You are able to trigger the opening of Instant Shopping flow without a user click on the Instant Shopping button. You can use the JavaScript API open , provided that you have previously set up Instant Shopping as outlined in the integration guide.

One example is shown below:

1
2
3
4
5
6
7
8
9
10
11
12
  <script>
    window.klarnaAsyncCallback = function () {
      Klarna.InstantShopping.load({
        // setup options here
      }, function (callbackData) {
        // Instant Shopping is properly loaded
        if (customerFromSocialMedia) {
          Klarna.InstantShopping.open()
        }
      })
    }
  </scipt>

The open function accepts optionally a callback function. The data provided to this callback function are:

show_fullscreen: true or false,
error: with information about possible errors

Update order callback (server-side)

On several points during the Instant Shopping flow and according to customer interaction, our server-side performs calls at the merchant_urls.update which allow you to update the order accordingly. The request includes an “update_context” property and the “button_key” to help you decide what kind of updates you want to make.

when customer clicks on the Button for the first time and a new session is created: “update_context: 'session_initialized'”
when the session is updated as a result of the integrator calling the JavaScript API update: “update_context: 'session_updated'”
when customer adds or updates their address: “update_context: 'identification_updated'”
when customer chooses a specific product variant from all the available product variations (items) and/or the quantity is changed: “update_context: 'specifications_selected'”

To update the order you need to return an appropriate HTTP response. If you do not want to perform any changes, then you need to return a response with HTTP 304 status code.

You should consider this step as optional and only utilise it if needed. Otherwise it is advised to leave merchant_urls.update not specified which will result in no update call.

Note: Read about Klarna’s API URLs to know the base URL.

Request prompt for order update

During this request we make available to you the details of the current state of order. Below you see an example of how the request body may look like.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
POST https://example.com/updateOrder.php
Content-Type: application/json
{
  "button_key": "123e4567-e89b-12d3-a456-426655440000",
  "update_context": "identification_updated"
  "integrator_url": "https://example.com/products/an-awesome-product.php",
  "purchase_country": "SE",
  "purchase_currency": "SEK",
  // ...
  "order_amount": 16900,
  "order_tax_amount": 3380,
  "order_lines": [{
    "type": "physical",
    "reference": "19-402",
    "name": "Battery Power Pack",
    "quantity": 1,
    "unit_price": 11900,
    "tax_rate": 2500,
    "total_amount": 11900,
    "total_discount_amount": 0,
    "total_tax_amount": 2380,
    "product_url": "https://www.example.com/products/f2a8d7e34",
    "image_url": "https://www.example.com/products/f2a8d7e34"
  }, {
    "type": "shipping_fee",
    "reference": "express_priority",
    "name": "EXPRESS 1-2 Days",
    "quantity": 1,
    "unit_price": 5000,
    "tax_rate": 2500,
    "total_amount": 5000,
    "total_tax_amount": 1000
  }],
  "selected_shipping_option": ...
  // ... the rest of the order information, if present
  "items" : [],
  "attachment": {},
  "merchant_data": "",
  "merchant_reference1": "",
  "merchant_reference2": ""
}

At this point it is possible to decide whether the order should be updated based on the current order’s state. A example use case could be applying additional sales tax depending on consumer’s address.

Skip order update

If there is no need to perform any update then it is recommended to return 304 HTTP response - NOT MODIFIED. As a result no changes will be applied as a part of this call.

No updates for order - response with code:

The no-update response looks like below:

1
HTTP 304 No-Content

Perform order update

If you decide to update the order, then you need to include updated data in the response. Currently we support updating the following fields: order_lines, merchant_data, shipping_options.

Update order response

The response of the order update should include desired order data changes. Example response containing updated order lines:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
HTTP 200 Success
Content-Type: application/json
{
  "order_lines": [{
    "type": "physical",
    "reference": "19-402",
    "name": "Battery Power Pack",
    "quantity": 1,
    "unit_price": 11900,
    "tax_rate": 2500,
    "total_amount": 11900,
    "total_discount_amount": 0,
    "total_tax_amount": 2380,
    "product_url": "https://www.example.com/products/f2a8d7e34",
    "image_url": "https://www.example.com/products/f2a8d7e34"
  }, {
    "type": "sales_tax",
    "reference": "Sales Tax",
    "name": "VAT",
    "quantity": 1,
    "unit_price": 1000,
    "tax_rate": 0,
    "total_amount": 1000,
    "total_tax_amount": 0
  }],
  "shipping_options": [{
    //... updated shipping options here
  }],
  "merchant_data": "" // updated merchant_data
}

Allowing customer to specify product attributes

This features is when the products sold have attributes, like color and size that need to be specified by the customer, and the Instant Shopping flow is the first thing your customers will land onto. It is a common scenario for direct links to the onsite pages from instagram and other social media posts, or when your products are being sold completely offsite, like in a blogger’s site.

To leverage this feature you will need to specify all the available product variations either when supplying the options to the Javascript load API, or when setting up a new button key for offsite use. Note that a product variation needs to include the information an order line item should have and additionally some information for its attributes.

The example below refers to selling a T-shirt and allowing customers to choose between available colors (black, white and green) and sizes (medium and large). The schema allows the flexibility to define that:

The T-Shirt in black and medium is not available
The T-shirt in large costs more
The T-shirt in green has a discount

The options below can by supplied in two ways depending on your use case:

onsite: as input to Javascript API load
offsite: as input to creating a new button key for offsite use

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
{
  // the rest of parameters goes here...
  "items": [
    {
      "type": "physical",
      "available": true,
      "reference": "19-402-USA-MW",
      "name": "T-Shirt",
      "unit_price": 11000,
      "total_amount": 11000,
      "total_tax_amount": 1000,
      "tax_rate": 1000,
      "total_discount_amount": 0,
      "image_url": "https://www.exampleobjects.com/tshirt-medium-white.png",
      "group_identifier": "19-402-USA",
      "product_attributes": [
        {
          "identifier": "size",
          "identifier_label": "Size",
          "value": "M",
          "value_label": "Medium"
        },
        {
          "identifier": "color",
          "identifier_label": "Color",
          "value": "W",
          "value_label": "White"
        }
      ]
    },
    {
      "type": "physical",
      "available": true,
      "reference": "19-402-USA-LW",
      "name": "T-Shirt",
      "unit_price": 11110,
      "total_amount": 11110,
      "total_tax_amount": 1010,
      "tax_rate": 1000,
      "total_discount_amount": 0,
      "image_url": "https://www.exampleobjects.com/tshirt-large-white.png",
      "group_identifier": "19-402-USA",
      "product_attributes": [
        {
          "identifier": "size",
          "identifier_label": "Size",
          "value": "L",
          "value_label": "Large"
        },
        {
          "identifier": "color",
          "identifier_label": "Color",
          "value": "W",
          "value_label": "White"
        }
      ]
    },
    {
      "type": "physical",
      "available": false,
      "reference": "19-402-USA-MB",
      "name": "T-Shirt",
      "unit_price": 11000,
      "total_amount": 11000,
      "total_tax_amount": 1000,
      "tax_rate": 1000,
      "total_discount_amount": 0,
      "image_url": "https://www.exampleobjects.com/tshirt-medium-black.png",
      "group_identifier": "19-402-USA",
      "product_attributes": [
        {
          "identifier": "size",
          "identifier_label": "Size",
          "value": "M",
          "value_label": "Medium"
        },
        {
          "identifier": "color",
          "identifier_label": "Color",
          "value": "B",
          "value_label": "Black"
        }
      ]
    },
    {
      "type": "physical",
      "available": true,
      "reference": "19-402-USA-LB",
      "name": "T-Shirt",
      "unit_price": 11110,
      "total_amount": 11110,
      "total_tax_amount": 1010,
      "tax_rate": 1000,
      "total_discount_amount": 0,
      "image_url": "https://www.exampleobjects.com/tshirt-large-black.png",
      "group_identifier": "19-402-USA",
      "product_attributes": [
        {
          "identifier": "size",
          "identifier_label": "Size",
          "value": "L",
          "value_label": "Large"
        },
        {
          "identifier": "color",
          "identifier_label": "Color",
          "value": "B",
          "value_label": "Black"
        }
      ]
    },
    {
      "type": "physical",
      "available": true,
      "reference": "19-402-USA-MG",
      "name": "T-Shirt",
      "unit_price": 10000,
      "tax_rate": 1000,
      "total_tax_amount": 1000,
      "total_discount_amount": 2000,
      "total_amount": "9000",
      "image_url": "https://www.exampleobjects.com/tshirt-medium-green.png",
      "group_identifier": "19-402-USA",
      "product_attributes": [
        {
          "identifier": "size",
          "identifier_label": "Size",
          "value": "M",
          "value_label": "Medium"
        },
        {
          "identifier": "color",
          "identifier_label": "Color",
          "value": "G",
          "value_label": "Green"
        }
      ]
    },
    {
      "type": "physical",
      "available": true,
      "reference": "19-402-USA-LG",
      "name": "T-Shirt",
      "unit_price": 10000,
      "tax_rate": 1000,
      "total_tax_amount": 1000,
      "total_discount_amount": 2000,
      "total_amount": "9000",
      "image_url": "https://www.exampleobjects.com/tshirt-large-green.png",
      "group_identifier": "19-402-USA",
      "product_attributes": [
        {
          "identifier": "size",
          "identifier_label": "Size",
          "value": "L",
          "value_label": "Large"
        },
        {
          "identifier": "color",
          "identifier_label": "Color",
          "value": "G",
          "value_label": "Green"
        }
      ]
    }
  ]
}

The properties that control how Instant Shopping will present the selectors of the different product specifications are group_identifier and product_attributes:

group_identifier: is a string, a uniqie identifier of grouping all product variations into one product_attributes
product_attributes: is an array of items, each one representing a specific product attribute. So for a product of specific color and size, this array should contain two items.
product_attributes[].identifier: is a string, a unique identifier of this product attribute, e.g. “clr”
product_attributes[].identifier_label: is a string, a human redable, localized text of the product attribute, e.g. “Color” in English or “Färg” in Swedish
product_attributes[].value: is a string, a unique identifier of this product attribute value, e.g. “w”
product_attributes[].value_label: is a string, a human redable, localized text of the product attribute value, e.g. “White” in English or “Vit” in Swedish

Documentation

Partners

Resources

Branding Guidelines

Go To

Additional Features

Choose between Klarna themes

Choose between button types

Direct distribution links for Button Keys suitable for offsite

Programmatically open up the Instant Shopping flow

Update order callback (server-side)

Request prompt for order update

Skip order update

Perform order update

Allowing customer to specify product attributes

Documentation

Partners

Resources

Branding Guidelines

Go To

Additional Features

Choose between Klarna themes

Choose between button types

Direct distribution links for Button Keys suitable for offsite

Subscribe to events from JavaScript

Programmatically open up the Instant Shopping flow

Update order callback (server-side)

Request prompt for order update

Skip order update

Perform order update

Allowing customer to specify product attributes