FAQ

General

All non-technical questions to the product.

What is KSS?

The Klarna Shipping Service (KSS) is the shipping selector for the checkout.

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

Who can use KSS?

KSS is available for Klarna Checkout version 3 (KCOv3) merchants.

What does it cost?

KSS is free of charge as long as we receive the tracking information for sent parcels. Many of our partners are able to provide us with the tracking information, which consists of tracking number and the carrier.

If a partner is not able to provide us with the tracking number, you can still use the Klarna Shipping Service. You have the following options:

  • You can provide us with the tracking number and carrier information via the order management API. Just follow these instructions .
  • If you are on a Klarna platform partner that already is providing us with the tracking number then KSS is free of charge. You can find all our partners here and whether they share the tracking number with us.
  • If you cannot or do not want to share the tracking number with us, you can use KSS for 0.5 SEK per finalised session. We will charge you automatically after you have activated the service in the merchant portal. The first 6 months are going to be free of charge.

What is the USP for consumers?

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

Where is the product available?

The available markets and other information to the roll-out can be found on our product page .

Merchants have to agree to the amendment to the merchant agreement. The amendment states the cost of KSS 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 KSS only if they accept the amendment.

Partners

Platforms, plugins and TMS partners.

What kind of partners does KSS have?

KSS works with the following partners:

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

Can I use Unifaun / Consignor in combination with platforms or plugins like Magento?

Yes, those solutions should be platform agnostic.

Which partners are available?

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

Can you support any new partners?

We are open to team-up with anybody to enable KSS for our merchants. You can send an e-mail to shipping@klarna.com , introducing us to your partner. We take over the rest!

Which Magento versions do you support?

We tested and verified the Klarna KCO Magento plugin supports the KSS integration with KCOv3 on a vanilla install of Magento 2.3.x and Magento 1.9.x. We will not be extending to earlier versions of Magento 2 as they fall out of support from Magento in the near future and the effort to support does not make sense on the timelines.

Features

Questions about how KSS really works.

How many shipping options does KSS expect and how are they filtered?

KSS 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.

How does KSS sort the shipping options in the UI?

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[]. KSS will display the options in the order in which they are returned via the API.

Where do the logos come from?

The carrier logos are managed by KSS 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.

What is an error and a fallback?

An error is when there are no available shipping options for the user. The fallback is triggered when the KSS 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 KSS 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.

Can we show shipping options for digital goods such as giftcards?

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

Technical

API and integration.

How does KSS work?

KSS has two modes of operation, basic flow and aggregator flow. In basic flow, we display the shipping options that the Merchant sets KSS has an API, the Shipping API. For every TMS-enabled KCO session, KSS calls this API to get the available shipping options which should be shown in the checkout.

Who can integrate the KSS API?

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

  • Merchant: Klarna customer.
  • TMS: A Transport Management System (TMS) manages logistics for Merchants and is able to provide KSS 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 KSS with the Merchant’s available shipping options based on the logic set by the Merchant.

What does an ideal integration look like?

An ideal integration with the KSS 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 .

How can I test my KSS integration?

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.

Should I change something in KCO to use KSS?

Yes. See this section .

Once the purchase is completed, how will the merchant receive the shipping information?

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 KSS and should be used to find the shipment that has been created during the purchase process.

Why are you not providing all the information about the shipment in the KCO API?

The KCO API does not have all the information that the user has selected in KSS. As an example, add-ons such as notifications are missing. The KSS API enables saving shipment information during the purchase process. Once the purchase is completed, a unique identifier can be provided to the shipment that was created during purchase. The merchant will get the unique identifier from KCO and can pick up the shipment to print the actual shipping label. This way the merchant does not have to handle every shipment information via the KCO integration. The shipment information is handled via KSS and the merchant only picks up the shipment that was created during purchase.

How do you configure tags support?

The tags are between the Merchant and the TMS or partner. All KSS 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 KSS payload is because the Merchant sent it to KSS. KSS 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.

What the heck are “addons”?

Addons are shipping option features that enhance the functionality and augment the UX behavior. This will be expanded over time as more shipping reservation configurations are required by merchants or carriers.

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):

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
{
    "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": [
        {
            "category": "notifications",
            "type": "sms",
            "required": false,
            "default": true
        },
        {
            "category": "notifications",
            "type": "email",
            "required": false,
            "default": false
        },
        {
            "category": "delivery",
            "type": "entry-code",
            "required": false,
            "default": false
        },
        {
            "category": "delivery",
            "type": "additional-instructions",
            "max_length": 100,
            "required": false,
            "default": false
        }
    ],
    "class": "express"
}

For “operational_hours”, what is the difference between “defaults” and “overrides”? Can we just use “overrides”?

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.

Will you handle a multilevel list of shipping and pick up in store? Can we send them to preselected stores?

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

The ‘get-shipping-options’ request has a currency field - what am I supposed to do with this?

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, KSS 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. This may require some legwork and investigation during the integration phase.

How will the Integrator return the prices for special shipping options like bulky goods?

The Order Management 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’s the deal with all those price and tax fields? Can’t we ignore most of them?

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.

Ok so, what are we supposed to calculate and what can we expect KSS to calculate?

KSS 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.

KSS 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.

How and when is the orderline shipping_fee set on the KCO order?

This is controlled by KCO, not by KSS.

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.
    • KCO manages the shipping_fee.
    • Only cart contains the shipping fee (set by KCO and reflecting on what is currently selected in KSS).
    • During purchase, the order lines (retrieved on a merchant_read) do not have shipping_fee.
    • Once the order is completed, KCO adds a shipping_fee order line.
  2. Callback configured.
    • Merchant is expected to update shipping_fee based on the selected shipping option by responding with updated order lines.
    • Attributes of interest (on selected shipping option):
    • Both merchant cart and order lines contain the shipping_fee.

Why is the shipping_fee missing on the order lines when doing a KCO merchant read?

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

Why does the total amount not include shipping fee when doing a KCO merchant read?

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.

I don’t get the authorization request example. How does authorization work?

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 KSS with the provided Identifier and Key.

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

1
2
Identifier: ‘sweMerch123’
Key: ‘smOOOth’

As the Klarna Shipping Service (KSS) prepares its authorization request to the Integrator, it generates a random string, called a Nonce. KSS 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 KSS provided the Nonce 'lRFUpqW7Xd':

1
2
3
Nonce: ‘lRFUpqW7Xd’
Nonce+Key: ‘lRFUpqW7XdsmOOOth’
Digest: ‘8C3891B3162DB3AB61A9B2DA74E6A479553ABA897894E5236ED290C11A0B832B’

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

1
2
3
4
5
6
7
{
    "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 KSS, running the Sha256 algorithm on that value to create their own Digest, and then comparing that Digest to the Digest provided by KSS. If the Digests are identical, the Integrator accepts the request and returns a bearer token.

Other

Anything else regarding shipping.

How can merchants show DHL packstation in KCOv3?

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"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,
        "shipping_method": "DHLPackstation",
    },
    ...
]