A guide to implement the Shipping API
An ideal integration with the Shipping API enables the following:
Please note that in order to use the Klarna Shipping Assistant you may have to adjust your Checkout integration. More info about that in this section.
This section describes how to authorize requests from the Klarna Shipping Assistant.
User has entered the checkout and Klarna tries to obtain authentication from the Integrator.
Merchant has provided Klarna with authentication credentials.
Communications between the Klarna Shipping Assistant and the Integrator need to be authenticated using a bearer token scheme. This means each request has a header like this:
<token> is a secret string provided by the Integrator. To obtain it, Klarna Shipping Assistant calls
POST /auth with credentials provided by the Merchant. This is the payload:
The digest is calculated by concatenating the (random) nonce and the (Merchant-provided) key and then feeding the result into the SHA-256 algorithm. To check that the secret is correct, the Integrator must compare our value by doing the same process in their end:
We recommend the Integrator to give a unique token per merchant, and to let the token expire after a reasonable time (1h is a good duration). If the Klarna Shipping Assistant provides an old or wrong token to a call other than
POST /auth, the Integrator must answer with HTTP 401 (Unauthorized). If the Klarna Shipping Assistant provides the wrong credentials to
POST /auth, the integrator must also answer with HTTP 401 (Unauthorized).
The Klarna Shipping Assistant will cache the bearer token until an HTTP 401 response is received, and then fetch a new one.
This section describes what preview options are, and how to set them.
User has entered the checkout.
No address data is available for the user.
When a new user enters the checkout, Klarna has no data to pre-fill the address. To ensure a user-friendly experience, we show placeholder options based only on the country of purchase. These temporary options are called preview options.
This is how it looks like:
To make this work, the Integrator needs to be able to return shipping options for partial address data on a
POST /shippingoptions call (described in the next section). This could be only the country, in cases like the above. The Integrator must mark these options with the preview flag. Once Klarna has a full address, the Klarna Shipping Assistant will call the endpoint again with the complete information, and the Integrator must answer with fully valid (non-preview) shipping options.
This section describes how to provide shipping options to the Klarna Shipping Assistant.
User is in the checkout and has provided address data or their address data is prefilled.
Complete address data is available for the user, and the authentication call to the Shipping API was successful.
The Klarna Shipping Assistant obtains shipping options from the Integrator by calling
POST /shippingoptions every time the user updates their cart or address information. This call must be authenticated using the bearer token obtained in step 1.
You can test a Shipping API implementation and see how the shipping selector looks in our test tool, Shipwreck. This is an example request from Shipwreck:
Klarna passes on the order information to the Shipping API. The order information is set by the Merchant while creating a Checkout session.
To enhance the shipping experience, we added shipping attributes to the order and order line level. These attributes, just like the rest of the order information, will be passed on to the shipping API. The attributes can be used to set the rules which shipping options should be shown.
This is an example response from an Integrator (adapted from our test integration, Ghostship):
You can find the complete list of supported shipping types, services and carriers in our API documentation. Below you can find a short summary of the key information.
Each shipping option must have a shipping type indicating whether for example it is a home delivery option. These are the currently supported types:
delivery-address- Delivery to door / address. Final selected option will contain an address, and can contain a timeslot.
pickup-box- Delivery to a pickup locker/box. Final selected option will contain a location.
pickup-point- Delivery to a pickup point. Final selected option will contain a location.
pickup-merchant-store- Delivery to a merchant store for pickup. Final selected option will contain a location.
postal- Delivery of a package/letter using the postal network.
generic-pickup- Delivery to a pickup point when location is unknown.
generic-shipping- Shipping option when the carrier decides shipping method.
office-delivery- Delivery to an office address. For eg. to an office reception.
boat-delivery- Delivery by boat.
digital- Delivery via e-mail or SMS.
The type controls which name we show in the shipping option. For example,
delivery-address is shown in English as “To door delivery”.
In case there is a digital item in the order, the banner about digital delivery will be shown. When the order has a digital item but no physical items, Klarna Shipping Assistant will not request any shipping options from TMS and the shipping selector will not be shown, and the shipping type will be set to
Add-ons are additional services or information that can be added to an option. They can be marked as mandatory. Here are some examples:
addon_notification- Booking email or sms notification. Final selected option will contain an email address and/or a phone number.
addon_delivery- Adding entry code (door code) and delivery instructions. Final selected option will contain door code and instruction text.
A shipping option’s delivery time is crucial information for the users. It can be provided in two different formats:
This will be shown as 1-3 working days.
Assuming today is2019-08-27in Sweden (UTC+2in the summer), this will be shown as“Tomorrow at 14h”(Zis the same as+00:00: it indicatesUTC+0, Greenwich time).
This section describes the pickup point map and the associated location search.
User opens the pickup point map and searches for locations.
User inserted a new postal code to the location search field.
Pickup locations are presented on a map view. The user can search for new locations by postal code.
Whenever the user inserts a new postal code, Klarna will call
POST /shippingoptions with country and postal_code. The following swimlane explains the flow:
Be careful when implementing your
/shippingoptions endpoint. From the Integrator’s perspective, a location search looks like a preview options call, since it uses this endpoint with an incomplete address. However, Klarna Shipping Service discards any changes other than the locations.
This section describes how Klarna finalises the selected shipping option.
User is completing the purchase (pushing the buy button).
A valid (non-preview) shipping option is selected. The user has not tried to finalize before.
Receiving this call does not guarantee the purchase is final. If something fails, this can lead to a
PUT operation (see next section).
The first time the user tries to finalize their purchase by pressing the buy button, the Klarna Shipping Assistant validates the selected shipping option with
POST /shipment. Finalizing can fail for a number of reasons (for example, the payment method is rejected), so this is not a guarantee that the shipment is final. Depending on details explained in the next section, next attempts to finalize might instead be realised as
PUT /shipment/<shipment ID>.
If the Integrator receives valid data, they must respond with HTTP 201 (Created) and a valid payload:
<shipment ID> is a unique identifier for the (pre-reserved) shipment. The response must also set the
The shipment ID must be unique per
session_id (this is sent in the request payload). Its presence, and the presence of the location header, will be taken as confirmation that an entry has been correctly created in the Integrator’s service. This information will then be forwarded to the merchant once the purchase is confirmed, and they can print the shipping label.
This is the ideal workflow:
Klarna uses different identifiers during the API flow. To avoid confusion, please check this swimlane.
This is an example request from our test tool Shipwreck:
This section describes how and when the Klarna Shipping Assistant updates the finalized shipping option.
User tries to finalize after a previous finalize attempt.
POST /shipment call was successful (see previous section).
Klarna validates several items when the user completes their purchase (example shipping options, payment method). If any of those fail, the purchase will not proceed.
As an example, the
POST /shipment call may be successful, but the payment method may fail. The user then gets an error message and can change their details before trying again. This gives them a chance to change anything, like adding items to the cart or changing the shipping address. When the user is completing the checkout for the second time, the Klarna Shipping Assistant will validate the selected shipping option again to make sure the user’s choice is still valid.
If the Klarna Shipping Assistant has an available shipment ID from a previous
POST /shipment call, the following attempts to finalize will be realised as
PUT /shipment/<shipment ID> instead.
The Shipping API will not communicate whether the order is completed successfully. This means that the Klarna Shipping Service can update the shipping option several times, sometimes with long waits in between, until the order is placed. The merchant will know when the order is completed through the Order Management API.
This section describes how to provide Klarna with tracking information.
User has completed the purchase.
Order is successfully completed.
If the Integrator does not provide complete tracking information on the
POST /shipment/<shipment ID> or
PUT /shipment/<shipment ID> responses, the Klarna Shipping Assistant will call
GET /shipment/<shipment ID> periodically after the purchase is complete. The expected response format is the same as in the
The response to this call should list all shipments connected to this purchase, and it should contain tracking numbers (tracking_id) for each shipment. The tracking information is used by Klarna to allow users to track their parcels and get notified upon any updates.
Alternatively, you can provide us with the tracking number and carrier information via the order management API. Just follow these instructions.