FAQ

General

What is a TMS and an Integrator?

Integrator: The Integrator implements the Klarna Shipping Service Callback API as described in the documentation. The Integrator is the upstream provider of shipping options for KSS.

The Klarna Shipping Service Callback API enables communication between the Klarna Shipping Service and the Integrator. If you integrate the Klarna Shipping Service Callback API, Klarna will be able to fetch your shipping options and get the tracking number of the sent parcel.

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.

How can I test my KSS integration?

We provide an integration tool that allows you to interacts with the shipping selector as it would be presented within the checkout: https://shipwreck.playground.eu1.kss.klarna.net/?endpoint=https://ghostship.staging.eu1.kss.klarna.net&identifier=M001&key=secret1

The inputs on the left allows you to provide your own KSSCAPI endpoint and id/key so that you can actually see how the selector would adapt to the responses of the KSSCAPI implementation.

Authorization

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

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

Identifier: ‘sweMerch123’
Key: ‘smOOOth’

As the Klarna Shipping Service (KSS) prepares its authorization request to the Integrator, it generates a random Nonce. KSS appends the Key to the Nonce, and then runs the Sha256 algorithm on that value to create a Digest.

To further the example, let’s say KSS provided a Nonce of ‘lRFUpqW7Xd’:

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

Then KSS sends the authorization request with the Identifier, Nonce, and Digest.

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.

Shipping options

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 athe merchant wants to display all available options, it is possible. The KSS integration tool will allow to test what the different setups would look like, to help merchants decide what works best.

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.

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.

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 examples isisare the “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 along or a specific date.

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

As a general rule the KSSCAPI is passive and expects that the Merchant and the TMS or partner to 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.

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.