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 Instant Shopping Button Keys 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 on your pages.

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

Klarna dark theme

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

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

Klarna default theme

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

You can use Instant Shopping without including the buy button that Instant Shopping adds on the page. Instead you will develop and own a buy button according to your liking and interact with the JavaScript API to offer the purchase flow.

1. Use your own button In order for the Instant Shopping buttton to not be shown, all you need to do is add a flag to the options with which you load Instant Shopping through JavaScript.

This property is called include_button and should be set to false when you trigger the load JavaScript API method. The example below shows how you can use this:

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
window.klarnaAsyncCallback = function () {
  window.Klarna.InstantShopping.load({
    "setup": {
      "instance_id": "button-123abc456",
      "key": "123e4567-e89b-12d3-a456-426655440000",
      "environment": "production",
      "region": "eu"
    },
    "include_button": false,
    "purchase_country": "SE",
    "purchase_currency": "SEK",
    "locale": "en-SE",
    "merchant_urls": {
      "terms": "https://example.com/terms"
    },
    "items": [
      {
        "type": "digital",
        "reference": "subscription-3m",
        "name": "3 month subscription at 29.99/month",
        "unit_price": 2999,
        "tax_rate": 0,
        "total_amount": 2999,
        "total_tax_amount": 0,
        "image_url": "https:/example.coma/subscription-logo.svg",
        "group_identifier": "subscription",
        "product_attributes": [
          {
            "identifier": "suscription_type",
            "identifier_label": "Subscription type",
            "value": "3m",
            "value_label": "3 month subscription at 29.99/month"
          }
        ]
      },
      {
        "type": "digital",
        "reference": "subscription-6m",
        "name": "6 month subscription at 19.99/month",
        "unit_price": 1999,
        "tax_rate": 0,
        "total_amount": 1999,
        "total_tax_amount": 0,
        "image_url": "https:/example.coma/subscription-logo.svg",
        "group_identifier": "subscription",
        "product_attributes": [
          {
            "identifier": "suscription_type",
            "identifier_label": "Subscription type",
            "value": "6m",
            "value_label": "6 month subscription at 19.99/month"
          }
        ]
      },
      {
        "type": "digital",
        "reference": "subscription-12m",
        "name": "12 month subscription at 9.99/month",
        "unit_price": 999,
        "tax_rate": 0,
        "total_amount": 999,
        "total_tax_amount": 0,
        "image_url": "https:/example.coma/subscription-logo.svg",
        "group_identifier": "subscription",
        "product_attributes": [
          {
            "identifier": "suscription_type",
            "identifier_label": "Subscription type",
            "value": "12m",
            "value_label": "12 month subscription at 9.99/month"
          }
        ]
      }
    ]
  }, function (response) {
    console.log('Klarna.InstantShopping.load callback with data:' + JSON.stringify(response))
  })
}

2. Respond to customers click on your button It is necessary that you capture the click to your button so that you can in turn open the Instant Shopping purchase flow.

To achieve this you will use the JavaScript API of open. An example is provide below:

1
2
3
4
5
6
7
8
9
  document.getElementById('my-instant-shopping-button').onclick = function (e) {
    window.Klarna.InstantShopping.open({
      setup: {
        instance_id: 'button-123abc456'
      }
    }, function (response) {
      console.log('Klarna.InstantShopping.open callback with data:' + JSON.stringify(response))
    })
  }

Instant Shopping offers an API to register and “listen to” events that happen during the purchase flow. You can choose to register to front-end or back-end or both, depending on your needs. Some examples are:

• You need to provide different shipping options depending on the address of the customer
• You need to add a sales tax to the order_lines depending on the address of the customer
• You need to gather analytics about the customer actions

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 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
4
5
  window.Klarna.InstantShopping.on('confirmation_displayed', function (callbackData) {
     console.log('The smoooth confirmation view is displayed. Order Id', callbackData.order_id)
  }, {
    setup: { instance_id: 'button-123' }
  })

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

1
2
3
  window.Klarna.InstantShopping.off('confirmation_displayed', {
    setup: { instance_id: 'button-123' }
  })

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

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, if needed. 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.

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.

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

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
}

When creating a button key from the server side:

• You should set allow_separate_shipping_address to true if you want to offer separate shipping and billing. If this flag is false or not set, the displayed delivery options will be based on the billing address.

The following you can do either while configuring an Instant Shopping display through the JavaScript API from the client side, or while creating a button key through the REST API from the server side.

• You must send fallback shipping options for every Instant Shopping shown. These are used if the Integrator fails to provide real time data. (JavaScript API | REST API)

• You can indicate with the property shipping_countries the list of countries to which you ship. If it’s not set, it will default to the purchase country only. (JavaScript API | REST API)

• You can define shipping_attributes

  • at the order level. (JavaScript API | REST API)
  • at the order line level. (JavaScript API | REST API) These are passed on to the Shipping API and can influence the available shipping options.
    • Shipping attributes are weight, dimensions, and tags.

• When an order is authorized you will receive a ping to approve or decline the order at the merchant_urls.place_order endpoint. This endpoint you have defined when creating the button key. The request will include the authorized order, including information about the selected_shipping_option which includes the tms_reference.