All non-technical questions to the product.

The Klarna Shipping Assistant (KSA) is the shipping selector for the checkout.

“Give shoppers the power to choose their delivery experience. Stay in control and boost conversion with your shipping rules and our user-friendly design.”

KSA is available for Klarna Checkout version 3 (KCOv3) Merchants.

KSA is free of charge for the first six months. After that, it costs 0.50 SEK per completed session. If you are able to supply parcel tracking information, you may be eligible for a discounted rate.

Choose where, when and how your parcel will be delivered.

Sweden, Norway, Finland, Denmark, Germany, Austria, The Netherlands, The UK and the US - although KSA ships to all countries globally. More information can be found on our product page.

Merchants have to agree to the amendment to the Merchant agreement. The amendment states the cost of KSA as well as the right for Klarna to use data such as the tracking. Merchants will have to accept the amendment in the Merchant portal. Merchants are allowed to configure KSA only if they accept the amendment.

Platforms, plugins and TMS partners.

KSA works with the following partners:

• Transport Management System (TMS) partners: such partners manage the logistics of Merchants. TMS partners integrate with KSA in order to provide us the available shipping options. The Merchants define in their TMS system which options should be shown in KSA, and the TMS sends those options to KSA for every KCO session.
• Platform & plugin partners: such partners help Merchants to manage their KCO integration. If Merchants want to enable KSA, they have to manage some settings via the platform or plugin partner.

Yes, those solutions are platform agnostic.

Here you can find the overview about our partnerships which are available to our Merchants on production.

We are open to team-up with anybody to enable KSA for our Merchants. Please reach out!

Questions about how KSA really works.

KSA has no expectations or logic regarding the number or type of shipping and delivery options. If you want to filter options, it is up to you. If a Merchant wants to display all available options, it is possible.

Sorting is up to the Merchant. The Integrator can allow it to be customizable per Merchant, they can provide a series of configurations to the Merchant, or they can allow the Merchant to define the configuration per-order via order.tags[]. KSA will display the options in the order in which they are returned via the API.

The carrier logos are managed by KSA itself. The Merchant logos are fetched from the Merchant portal. Merchants can upload their logos in the branding app.

The recommended ratio is 38/22. That’s the current size for the carrier logos as well.

An error is when there are no available shipping options for the user. The fallback is triggered when the KSA API is not able to fetch the available shipping options for any other reason.

We enter fallback whenever the TMS configuration is set (there should be remote calls to the TMS) but we do not receive an answer that is compliant with the KSA API. This could happen on the POST /shippingoptions call if:

• The configuration is wrong.
• TMS is not replying.
• TMS cannot be reached.
• TMS replies with a server failure code (5XX).
• TMS returns an invalid response (invalid response typically means an HTTP code that is not listed in the API specification, content that is not a single valid JSON object, or JSON that does not conform to the API specification).

If the TMS returns a valid HTTP error code on (POST|PUT) /shipment, we will instead try to restart the flow. Any error on POST /shippingoptions will trigger a fallback.

For now, we do not handle digital shipping. If there are no physical items in the cart:

• The fallback shipping options via KCO should have only 1 option.
• the shipping method of that 1 shipping option should be of type “digital”.
• allow_separate_shipping_address should be false.

API and integration.

KSA has an API, the Shipping API. For every TMS-enabled KCO session, KSA calls this API to get the available shipping options which should be shown in the checkout.

The Integrator is the upstream provider of shipping options for KSA. The Integrator can be:

• Merchant: Klarna customer.
• TMS: A Transport Management System (TMS) manages logistics for Merchants and is able to provide KSA with a Merchant’s available shipping options based on the logic set by the Merchant.
• Partner: Klarna partner. Can also manage the logistics of a Merchant through their own integration with a TMS and is able to provide KSA with the Merchant’s available shipping options based on the logic set by the Merchant.

An ideal integration with the KSA API enables the following:

• Shipping options can be shown in the checkout
• Selected shipping option of the user is saved and a preliminary shipment is created (later this can be used by the Merchant for printing the actual shipping label).
• Tracking is available after purchase

We recommend for enterprise Merchants to implement our API directly or use one of our partners. For SMEs we recommend to work with our partners. More info here.

We provide Shipwreck, an integration tool that allows you to interact with the shipping selector as it would be presented within the checkout. The inputs on the left allows you to provide your own endpoint and id/key so that you can see how the selector would adapt to the responses of the API implementation.

Yes. See this section.

We extended the KCO order with selected_shipping_option. We provide all the information including selected pick-up point, see here. The recommended integration flow is to use the tms_reference for shipment booking. This unique identifier comes from KSA and should be used to find the shipment that has been created during the purchase process.

The tags are between the Merchant and the TMS or partner. All KSA does is pass along whatever the Merchant supplies along with the order. So if they have a tag called PRIME which indicates a 10% discount, they would have to tell the TMS or partner through some sort of configuration (in advance). The only reason why that would be set in the KSA payload is because the Merchant sent it to KSA. KSA has no idea how to process or read tags, they are defined by and between the Merchant and the TMS or partner. Tags can be configured on order and order line level.

Yup. The default is just for simple cases with very general data, but “overrides” allows the Integrator to specify day-by-day hours or a specific date. If operational hours are not known, the object should not be supplied.

KSA (as opposed to the old basic shipping selector in KCO) can present multilevel lists like showing pick-up points or stores.

As a general rule the Shipping API is passive and expects that the Merchant and the TMS or partner knows what to expect from each other. If we send the Integrator an ISO currency code as part of the order, KSA is just saying that the currency values in the order are in that currency, which is only possible if the Merchant supports that on their end. So care must be taken to ensure that the Merchant can not create an order using a currency that is unsupported by the Integrator they have partnered with for that order.

The Checkout API allows the Merchant to set weight and dimension attributes to each order line. It also allows setting custom tags to each order line and to the whole order. We forward these tags to the Integrator, so they can be used to control shipping behavior (e.g., Merchant can define the tag ‘’dangerous_goods’’ for specific products, so that the Integrator knows the price of such shipping options based on the tag).

What price fields the Integrator wants to ignore is entirely up to them. The “total_amount”, “total_tax”, and “total_price_including_tax” fields are always provided, and it is certainly possible that those alone are enough. The order line, tax, and discount distinctions are provided so that the Integrator can support more sophisticated functionality, where maybe some items ship separately at different rates, or maybe price is based on order line value with or without tax.

For example, “total_discount_amount” is already accounted for in the “total_price_including_tax” field. It is provided so that the Integrator can support a pricing scheme or promotion with a Merchant based on the price of the order with discounts taken into account. So if the promotion is that all orders over 1000 SEK get free shipping, and a User places an order that is 950 SEK with a 100 SEK discount from 1050 SEK, the Integrator and the Merchant can work out whether or not that order would qualify for the promotion.

KSA will pass along all tax and total amounts for the order itself - the Integrator doesn’t have to calculate anything regarding the “cart” or its items.

KSA expects that the Integrator will calculate and include the correct and appropriate VAT in the shipping_option.price and also provide the correct and appropriate VAT rate in the shipping_option.tax_rate field.

This is controlled by KCO, not by KSA.

There are two ways and they depend on if the shipping_option_update merchant callback is configured in KCO or not:

1. Callback NOT configured.
   undefinedundefinedundefinedundefined
2. Callback configured.
   undefinedundefinedundefined

This is expected in the cases where the Merchant has not configured Merchant callback and the order is not completed. See aquestion above.

Normally, KCO adds the shipping fee as a separate order line when the order is completed (user presses the “buy” button), and it will be missing from the total_amount before that. If this does not happen, it means the Merchant has configured the Shipping Option Update callback, and should be setting the shipping fee themselves.

If you need to know the shipping fee ahead of time, you can always read it from the selected shipping option.

If you are not experiencing the default behavior, the recommended solution is to not use the callback. Alternatively, the callback response needs to include one order line of type shipping_fee, with the correct price.

Addons are shipping option features that allow shoppers to customize their shipments or opt-into extra things. Badges are small but eye-catching banners used to highlight particular USPs of a shipping option, e.g. “Express”.

The most basic example is notifications, which allow customers to request sms/email/phone notifications about delivery status. Here is a shipping option with a bunch of addons (you can view this behavior in the integration tool using our mock TMS - see the link above):

{     "id": "id-1050",     "type": "delivery-address",     "carrier": "budbee",     "name": "Budbee 2 home",     "price": 5000,     "tax_rate": 2500,     "preview": false,     "delivery_time": {         "earliest": "2019-02-03T00:00:00Z",         "latest": "2019-02-04T00:00:00Z",         "cutoff": "2019-02-01T23:00:00Z"     },     "addons": [         {             "type": "sms",             "required": false,             "default": true         },         {             "type": "leave-outside-door",             "required": false,             "default": false         },         {             "type": "sustainable-packaging",             "required": false,             "default": false,             "price": 350,         }     ],     "features": [         {             "class": "badge",             "type": "eco-friendly"         }     ] }

When you have an agreement with a TMS, the TMS provides you with an Identifier and a Key. You can then configure Klarna to use KSA with the provided Identifier and Key.

So, let’s say you as a Merchant have these credentials:

Identifier: ‘sweMerch123’
Key: ‘smOOOth’

As the KSA prepares its authorization request to the Integrator, it generates a random string, called a Nonce. KSA appends the Key to the end of the Nonce, and then runs the Sha-256 algorithm on that value to create a Digest.

To further the example, let’s say KSA provided the Nonce 'lRFUpqW7Xd':

Nonce: ‘lRFUpqW7Xd’
Nonce+Key: ‘lRFUpqW7XdsmOOOth’
Digest: ‘8C3891B3162DB3AB61A9B2DA74E6A479553ABA897894E5236ED290C11A0B832B’

Then KSA sends the authorization request with the Identifier, Nonce, and Digest, grouped like this:

{
    "identifier": "sweMerch123",
    "secret": {
        "digest": "8C3891B3162DB3AB61A9B2DA74E6A479553ABA897894E5236ED290C11A0B832B",
        "nonce": "lRFUpqW7Xd"
    }
}

The Integrator authenticates the credentials by looking up their local Key for the Identifier, appending the Key to the Nonce provided by KSA, running the Sha256 algorithm on that value to create their own Digest, and then comparing that Digest to the Digest provided by KSA. If the Digests are identical, the Integrator accepts the request and returns a bearer token.

Anything else regarding shipping at Klarna.

In KCOv2, Merchants can enable packstation with the boolean packstation_enabled when creating a KCO session. This has changed for KCOv3.

In KCOv3, Merchants can provide shipping options for any order when creating a KCO session. The shipping options should be provided by using the shipping_options field. In order to show DHL packstation as a shipping option, the Merchant must send a shipping option with shipping_method set to DHLPackstation. DHL has a special address form that asks for the packstation number and customer number. This DHL address form is automatically shown if a Merchant is sending in DHL as a shipping method.

Here you can find the API documentation.

Example:

"shipping_options": [
    {
        "id": "dhl_packstation",
        "name": "DHL packstation",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "tax_amount": 0,
        "tax_rate": 0,
        "preselected": false,