Merchants have the option to add their own checkboxes to the final checkout screen for consumers to interact with.
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:
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:
See more about the Klarna Instant Shopping API Callbacks here.
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.
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 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'”
when shipping information was updated by customer: "`update_context: 'shipping_information_updated'`"
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.
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.
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.
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.
You can define shipping_attributes undefinedundefined
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.