Add additional checkboxes to the checkout screen
Merchants have the option to add their own checkboxes to the final checkout screen for consumers to interact with.
Merchant Checkbox Example
These checkboxes can be used for several purposes (marketing campaigns, etc.) and merchants can choose to show multiple in a single checkout screen. To implement this feature, merchants can either provide configuration via the Instant Shopping Button Keys API:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
POST /instantshopping/v1/buttons Authorization: Basic pwhcueUff0MmwLShJiBE9JHA== Content-Type: application/json { // other setup configuration here options: { additional_checkboxes: [ { id: 'checkbox-id-1', text: 'Click here to sign up for our monthly newsletter!' } ] } }
or when configuring a specific Instant Shopping flow through the JavaScript API load
or update
calls:
1 2 3 4 5 6 7 8 9 10 11 12 13
<script> window.klarnaAsyncCallback = function () { Klarna.InstantShopping.load({ // other setup configuration here additional_checkboxes: [ { id: 'checkbox-id-1', text: 'Click here to sign up for our monthly newsletter!' } ] }) } </script>
Retrieving checkbox values on order completion
When a consumer completes the Instant Shopping flow, the merchant will receive a ping to the place_order
(or create_customer_token
for tokenization use cases) url with information about the order being created.
Whether each checkbox has been selected or not will be included in this payload:
1 2 3 4 5 6 7 8 9 10 11
POST https://example.com/placeOrder.php Content-Type: application/json { // other information here order: { // other order information here merchant_requested: { 'checkbox-id-1': true } } }
See more about the Klarna Instant Shopping API Callbacks here .
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 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
<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
Events/ Callbacks
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
Front-end with JavaScript
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 beplayground
in testing mode;region
: the region, will beeu
for Europe orna
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 .
Back-end (server-side) callbacks
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.
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 }
Setup Klarna Shipping Assistant (TMS)
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 isfalse
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 theselected_shipping_option
which includes thetms_reference
.