How to integrate Instant Shopping into an Upsell Page

You complete this step leveraging the Instant Shopping Button Keys API from your server-side

As a first step you need to obtain a Button key which you can reuse for displaying the Instant Shopping button. This key is used to identify you as a merchant and also to link to some necessary configuration options.

To obtain a key you can use the Instant Shopping Button Keys Service. An example of a request to this service is given below. Note that you need to use your API credentials to authenticate.

The minimum information needed to setup a Key is the URL of an endpoint where the Instant Shopping Button’s server-side will ping you when an Order is authorized.

POST /instantshopping/v1/buttons
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
  "merchant_urls": {
    "place_order": "< mandatory, URL of an endpoint at the merchant side, which will receive a ping to place an order. (must be https, max 2000 characters) >"
  }
}

Upon success the response of this service will provide you the button key.

HTTP 201 Created
Content-Type: application/json
Location: /instantshopping/v1/buttons/123e4567-e89b-12d3-a456-426655440000
{
  "button_key": "123e4567-e89b-12d3-a456-426655440000",
  "merchant_urls": { /* ... */ }
}

You complete this step from your client-side

After successfully completing this part you should see the Instant Shopping Button.

You will need to make sure that the Instant Shopping Button Javascript SDK is available on the page you want to display the Instant Shopping Button.

To do this add the following script tag as soon as possible in the page (e.g. <head>).

<script>
  window.klarnaAsyncCallback = function () {

    // This is where you start calling Instant Shopping JS SDK functions
    //
    // Klarna.InstantShopping.load({....})

  };
</script>
<script src="https://x.klarnacdn.net/instantshopping/lib/v1/lib.js" async></script>

At this step you decide where you want to place the Instant Shopping button within the page by positioning the HTML container element.

It is important to add a data attribute named data-instance-id to this element, which will uniquely identify this button. Note that you will refer to the value of this attribute when you use the JavaScript API and need to provide the setup.instance_id option. This is particularly necessary if you want to show multiple buttons on the same page. In that case each data-instance-id should be different and unique for this page.

<klarna-instant-shopping data-instance-id="button-123abc456" />

You will now need to provide all the information necessary to support the purchase flow. This information refers to the product being promoted, relevant shipping options, locale, currency, etc.

Note that you will use the button key created from the previous step.

Below you see an example of the configuration options that are necessary for the consumer flow. Please note that the order_amount and order_tax_amount will be calculated by the service.

Consult our Javascript Docs for more information.

2.c.1 Load the Instant Shopping

The klarnaAsyncCallback is executed as soon as the Instant Shopping Javascript SDK is ready.

You should define this function before the script tag for fetching lib.js (see 2.a) and as early as possible in the page, e.g. head.

You complete this step leveraging the Instant Shopping Button Keys API from your server-side

When the consumer has chosen to finalize the purchase, our server-side will ping you at the merchant_urls.place_order, and prompt you to place the order for a specific authorization_token. Remember that the URL for this endpoint was defined in the first step when you created this button key.

You will place the order through our REST API, and will be notified immediately about the successful or failed order placement. So you are able at this point already to create the order within your system.

You can choose to deny the purchase and in this case provide a deny reason and/or a URL to redirect the consumer to.

During this request we make available to you both the authorization_token to use next for placing the order, but also the details of the authorized order. Below you see an example of how the Request Body looks.

The response from the place order request is not important for Klarna Instant Shopping to progress the purchase flow.

Instead you should proceed with all validations (stock, shipping capabilities, prices, etc.) on your side. Once those are done, approve or deny the order following the request guidelines below.

Deny the order

If you need to deny the purchase you need to perform a DELETE call though our API and provide some information in the request body. Note that you need to use your API credentials to authenticate.

Below you may find an example of how a deny requests may look:

DELETE /instantshopping/v1/authorizations/{authorization_token}
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
  "deny_code": "address_error",
  "deny_message": "We cannot ship at this address."
}

Place the order

If you accept the order, then you need to place the order with our REST API. You do so by performing an HTTP POST in our API for the specific authorization_token and passing to the request body the complete Order. Note that you need to use your API credentials to authenticate.

Place order request

This is an example of how the Request could look like. Note that potential shipping fees are included in the order_lines object.

The response of the order placement endpoint may be success or failure.

HTTP 200 Success
Content-Type: application/json
{
  "order_id": "41475c53-b38e-427e-ade1-db78e3018e19",
  "fraud_status": "ACCEPTED"
}

HTTP 400 Bad Request
Content-Type: application/json
{
  "error_code": "bad_value",
  "error_message": "bad_value:locale"
}

When the purchase is completed the consumer is notified via suitable messaging within the Instant Shopping. There, we show a call-to-action button for directing the consumer to a new location. This location is the post-purchase page you have supplied through the merchant_urls.confirmation when setting up the Instant Shopping Button.

The URL of this page has already been defined either in the first step when you created this button key or in the step when you approved the order. If you choose to do this when you approve the order, then you can customize and personalize what this page will be for the specific consumer and purchase.

For instance with these merchant urls:

"merchant_urls": {
  "confirmation": "http://example.com/upsell-similar-product.php"
}

the consumer after closing our dialog will land to: http://example.com/upsell-similar-product.php

After the order is created, you can manage the order either manually via our Merchant Portal or through our Order Management API.