Klarna Shipping Service Callback API (1.3.0)

Download OpenAPI specification:Download

The Klarna Shipping Service Callback API enables communication between the Klarna Shipping Service and the Integrator.

Read more on Shipping assistant.

Authentication

TMSAuth

Security Scheme Type HTTP
HTTP Authorization Scheme basic

bearerAuth

Security Scheme Type API Key
Header parameter name: Authorization

Get an authorization token

Obtain a bearer authorization token. Aggregator specific merchant identifier and API key will be provided in the payload body, it's recommended that a merchant unique token is returned using a signed Json Web Token (JWT).

The token will be used for subsequent request for this merchant identifier using HTTP bearer authorization in the Authorization HTTP header with the format Authorization: Bearer <token>.

More about how this works:

When a Merchant has an agreement with the TMS, the TMS provides the Merchant with an Identifier and a Key. The Merchant then configures Klarna to use the TMS with the provided Identifier and Key. So let's say the TMS gives the Merchant these credentials:

Identifier: "sweMerch123"
Key: "smOOOth"

As KSS prepares its authorization request to the TMS, 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 TMS 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 TMS accepts the request and returns a bearer token.

Request
Request Body schema: application/vdn.klarna.shipping.auth-v1+json
identifier
string

Handled as a string. Should uniquely identify the merchant at the TMS and any configuration if different profiles are available.

object

API key/credentials for to authorize the merchant

Responses
201

Bearer token created successfully

400

The /auth request was malformed. In order to simplify debugging, the field failure_reason should contain a text describing the failure reason.

401

Invalid or missing credentials

post/auth
Request samples
application/vdn.klarna.shipping.auth-v1+json
{
  • "identifier": "merchant-12345-profile-65432",
  • "secret": {
    }
}
Response samples
application/vdn.klarna.shipping.auth-v1+json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudCI6ImZvb2JhciJ9.k2tE6vdJAEGbYSeZj2YluRK5vZbPAxsjd7XqARpBX3Y"
}

List shipping options

Gets shipping options for the given customer data, address and order lines.

It's always important to display proper expected delivery date and time, to create a smoooth customer experience. Below you can find a table with examples of how customer will see delivery date and time that is provided in the delivery_time field of shipping option. Representation can vary in case provided date points to the same date or a period, in case the date is today, tomorrow or any date in the future. Dates in the past are ignored.

Provided values UI presentation Examples
delivery_time.interval.earliest Delivered after delivery_time.interval.earliest business days Delivered after 3 business days
delivery_time.interval.latest Delivered within delivery_time.interval.latest business days Delivered within 3 business days
delivery_time.interval.earliest delivery_time.interval.latest Delivered in delivery_time.interval.earliest-delivery_time.interval.latest business days Delivered in 2-7 business days
delivery_time.interval.earliest delivery_time.cutoff Delivered after delivery_time.interval.earliest business days, if ordered before delivery_time.cutoff Delivered after 7 business days, if ordered before 14:00
delivery_time.interval.latest delivery_time.cutoff Delivered within delivery_time.interval.latest business days, if ordered before delivery_time.cutoff Delivered within 7 business days, if ordered before 14:00
delivery_time.interval.earliest delivery_time.interval.latest delivery_time.cutoff Delivered in delivery_time.interval.earliest-delivery_time.interval.latest business days, if ordered before delivery_time.cutoff Delivered in 1-5 business days, if ordered before 11:30
delivery_time.interval.earliest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered after delivery_time.interval.earliest business days between ca. delivery_time.time_of_day.earliest and delivery_time.time_of_day.latest Delivered after 3 business days between ca 17:00 and 18:00
delivery_time.interval.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered within delivery_time.interval.latest business days between ca. delivery_time.time_of_day.earliest and delivery_time.time_of_day.latest Delivered within 5 business days between ca 8:00 and 17:00
delivery_time.interval.earliest delivery_time.interval.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered in delivery_time.interval.earliest-delivery_time.interval.latest business days between ca. delivery_time.time_of_day.earliest and delivery_time.time_of_day.latest Delivered in 1-2 business days between ca 9:00 and 12:00
delivery_time.interval.earliest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered after delivery_time.interval.earliest business days between ca. delivery_time.time_of_day.earliest and delivery_time.time_of_day.latest, if ordered before delivery_time.cutoff Delivered after 4 business days between ca. 16:00 and 18:00, if ordered before 11:30
delivery_time.interval.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered within delivery_time.interval.latest business days between ca. delivery_time.time_of_day.earliest and delivery_time.time_of_day.latest, if ordered before delivery_time.cutoff Delivered within 3 business days between ca 10:00 and 17:00, if ordered before 11:30
delivery_time.interval.earliest delivery_time.interval.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered in delivery_time.interval.earliest-delivery_time.interval.latest business days between ca. delivery_time.time_of_day.earliest and delivery_time.time_of_day.latest, if ordered before delivery_time.cutoff Delivered in 1-5 business days between ca 15:00 and 17:00, if ordered before 11:30
delivery_time.earliest Delivered delivery_time.earliest at the earliest Delivered tomorrow at the earliest Delivered Thursday March 5 at the earliest
delivery_time.latest Delivered no later than delivery_time.latest Delivered today Delivered no later than tomorrow Delivered no later than Thursday, March 4
delivery_time.earliest delivery_time.latest Delivered between delivery_time.earliest and delivery_time.latest Delivered today Delivered no later than tomorrow Delivered tomorrow Delivered between Wednesday March 4 and Friday March 6 Delivered Monday April 6 Delivered between Monday April 6 and Friday May 24
delivery_time.earliest delivery_time.cutoff Delivered delivery_time.earliest at the earliest, if ordered before delivery_time.cutoff Delivered Saturday, July 25 at the earliest, if ordered before 15:00 Delivered tomorrow, if ordered before 14:00
delivery_time.latest delivery_time.cutoff Delivered no later than delivery_time.latest, if ordered before delivery_time.cutoff Delivered no later than Sunday, June 4, if ordered before 20:00 Delivered tomorrow, if ordered before 14:00
delivery_time.earliest delivery_time.latest delivery_time.cutoff Delivered between delivery_time.earliest and delivery_time.latest, if ordered before delivery_time.cutoff Delivered between Monday March 4 and Wednesday March 6, if ordered before 12:00 Delivered tomorrow, if ordered before 14:00
delivery_time.earliest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered delivery_time.earliest at the earliest, from delivery_time.time_of_day.earliest to delivery_time.time_of_day.latest Delivered Saturday March 13 at the earliest, from 15:00 to 17:00
delivery_time.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered no later than delivery_time.latest, from delivery_time.time_of_day.earliest to delivery_time.time_of_day.latest Delivered no later than Sunday November 9, from 9:00 to 15:00
delivery_time.earliest delivery_time.latest delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered between delivery_time.earliest and delivery_time.latest, from delivery_time.time_of_day.earliest to delivery_time.time_of_day.latest Delivered between Monday March 9 and Friday March 13, from 10:00 to 18:00
delivery_time.earliest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered delivery_time.earliest at the earliest, from delivery_time.time_of_day.earliest to delivery_time.time_of_day.latest, if ordered before delivery_time.cutoff Delivered tomorrow at the earliest, from 15:00 to 18:00, if ordered before 21:00
delivery_time.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered no later than delivery_time.latest, from delivery_time.time_of_day.earliest to delivery_time.time_of_day.latest, if ordered before delivery_time.cutoff Delivered no later than tmorrow, from 21:00 to 23:00, if ordered before 15:00
delivery_time.earliest delivery_time.latest delivery_time.cutoff delivery_time.time_of_day.earliest delivery_time.time_of_day.latest Delivered between delivery_time.earliest and delivery_time.latest, from delivery_time.time_of_day.earliest to delivery_time.time_of_day.latest, if ordered before delivery_time.cutoff Delivered between Monday March 9 and Friday March 13, from 15:00 to 17:00, if ordered before 11:30
Request
Security:
header Parameters
Authorization
required
string <string>

Authorization token on format Bearer <token>

Request Body schema: application/vdn.klarna.shipping.get_options-v1+json
currency
required
string

ISO 4217 alphabetic currency code.

geoblocking
boolean

A flag that indicates if the requested shipping options are for geoblocking flow.

Example: abc.se has consumers in e.g. Norway. According to Konsumentverket, these consumers should be given “the same opportunity to buy as a Swedish consumer”.

User Flows:

  1. A Norwegian consumer enters abc.se
  2. The consumer selects Norway as billing country and fills in his/her address
  3. Shipping module will display an information box saying “We do not deliver to the country specified in your billing address. Please select an alternative shipping option below.”
  4. The consumer chooses the delivery country (only if more than one is available).
    1. The consumer either fills in an address and gets a full set of shipping options OR
    2. The consumer chooses not to fill in an address and gets presented with only pickup-merchant-store shipping options with all the Swedish stores as locations.

locale
required
string <lc-CC>

IETF BCP-47 locale definition.

required
object (order)

Order definition

required
object (recipient)

Information about the recipient

selected_shipping_option_id
string

Informs what selected shipping option is currently selected by an enduser. When this information is provided it means that the API caller wants to refine the locations for the selected shipping option. The API endpoint should restrict its response to the selected shipping option only and base the refinement on the recipient data. The recipient data is temporary and should not replace any state persistent (if any) based on previous recipient data received in prior shippingoptions calls.

object (sender)

Information about the sender. Should indicate from where the goods are dispatched. This object is optional and can be empty.

session_id
required
string

Unique Klarna shipping session id.

Responses
200
400

The /shippingoptions request was malformed. In order to simplify debugging, the field failure_reason should contain a text describing the failure reason.

401

Invalid or expired token. A new token will be obtained.

post/shippingoptions
Request samples
application/vdn.klarna.shipping.get_options-v1+json
{
  • "currency": "SEK",
  • "geoblocking": true,
  • "locale": "sv-SE",
  • "order": {
    },
  • "recipient": {
    },
  • "selected_shipping_option_id": "tms-specific-shipping-option-id",
  • "sender": {
    },
  • "session_id": "201cda14-975f-4c4d-9c2f-12f3896b5156"
}
Response samples
application/vdn.klarna.shipping.get_options-v1+json
{
  • "shipping_options": [
    ]
}

Select shipping option

This operation reserves the user selected shipping option so that the merchant is able to query and find the data and create a shipment of it.

The shipment reservation should be unique per session_id provided in the request body.

This call happens when the user clicks buy, but before the purchase has gone through. A HTTP 201 response with a location header to this call is interpreted as a confirmation that the selected option is reserved, that the provided recipient data is valid and that the data has been saved successfully.

A HTTP 4xx error code will interrupt the purchase flow and restart the shipping selection process. See failure_reason.

If the purchase is successfully completed, KSS will call POST /shipment/{id}/confirm to confirm the reservation. See the /confirm call.

KSS will occasionally update a created shipment. This can happen because of a failure to finalize the order or for other reasons, which will restart the shipping selection process. See the PUT /shipment call. If the TMS is not able to return a shipment_id in the response, identifying the reserved shipment, then KSS is forced to invoke POST on succeeding updates instead of PUT.

Request
Security:
header Parameters
Authorization
required
string <string>

Authorization token on format Bearer <token>

Request Body schema: application/vdn.klarna.shipping.select_option-v1+json
currency
required
string

ISO 4217 alphabetic currency code

locale
required
string <lc-CC>

IETF BCP-47 locale definition

object (order)

Order definition

required
object

Information about the recipient

required
object
object (sender)

Information about the sender. Should indicate from where the goods are dispatched. This object is optional and can be empty.

session_id
required
string

Unique Klarna shipping session id.

Responses
200

Shipment reservation created and saved successfully

201

Shipment reservation created and saved successfully

400

The shipment reservation could not be created, for example if the recipient data is invalid or the selected shipping option is no longer available. The field failure_reason should be one of shipping_option_not_available, cutoff_time_expired or shipping_address_invalid, or if neither is applicable, a text describing the failure reason to simplify debugging.

401

Invalid or expired token. A new token will be obtained.

post/shipment
Request samples
application/vdn.klarna.shipping.select_option-v1+json
{
  • "currency": "SEK",
  • "locale": "sv-SE",
  • "order": {
    },
  • "recipient": {
    },
  • "selected_shipping_option": {
    },
  • "sender": {
    },
  • "session_id": "201cda14-975f-4c4d-9c2f-12f3896b5156"
}
Response samples
{
  • "additional_info": "string",
  • "selected_shipping_option": {
    },
  • "shipment_id": "c2059e35-58b1-4482-ad55-5e7ef541eae4",
  • "shipments": [
    ]
}

Get shipment status

Get carrier product codes for the shipment, shipment status and optional carrier tracking data.

Request
Security:
path Parameters
shipment_id
required
string

Unique shipment ID.

header Parameters
Authorization
required
string <string>

Authorization token on format Bearer <token>.

Responses
200

Successful operation.

401

Invalid or expired token. A new token will be obtained.

404

No such shipment.

get/shipment/{shipment_id}
Request samples
curl -i -X GET \
  'https://api.klarna.com/shipment/{shipment_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/vdn.klarna.shipping.get_shipment-v1+json
{
  • "additional_info": "string",
  • "selected_shipping_option": {
    },
  • "shipment_id": "c2059e35-58b1-4482-ad55-5e7ef541eae4",
  • "shipments": [
    ]
}

Update the shipping option

This operation updates the previously created shipment reservation (POST -> /shipment).

The shipment reservation should be unique per session_id provided in the request body.

This call happens when the user clicks buy, but before the purchase has gone through. This request takes place if relevant data were updated or if the user was denied a preceding purchase after /shipment call took place. The user then has the potential to change his previous selections and retry the purchase.

A HTTP 200 response with a location header to this call is interpreted as a confirmation that the selected option is reserved, that the provided recipient data is valid and that the data has been updated successfully.

A HTTP 4xx error code will interrupt the purchase flow and restart the shipping selection process. See failure_reason.

Request
Security:
path Parameters
shipment_id
required
string

Unique shipment ID

header Parameters
Authorization
required
string <string>

Authorization token on format Bearer <token>.

Request Body schema: application/vdn.klarna.shipping.select_option-v1+json
currency
required
string

ISO 4217 alphabetic currency code

locale
required
string <lc-CC>

IETF BCP-47 locale definition

object (order)

Order definition

required
object

Information about the recipient

required
object
object (sender)

Information about the sender. Should indicate from where the goods are dispatched. This object is optional and can be empty.

session_id
required
string

Unique Klarna shipping session id.

Responses
200

Shipment reservation updated successfully.

400

The pre-shipment could not be updated, for example if the recipient data is invalid or the selected shipping option is no longer available. The field failure_reason should be one of shipping_option_not_available, cutoff_time_expired or shipping_address_invalid, or if neither is applicable, a text describing the failure reason to simplify debugging.

401

Invalid or expired token. A new token will be obtained.

404

No such shipment (KSS will retry with a POST /shipment if this happens).

put/shipment/{shipment_id}
Request samples
application/vdn.klarna.shipping.select_option-v1+json
{
  • "currency": "SEK",
  • "locale": "sv-SE",
  • "order": {
    },
  • "recipient": {
    },
  • "selected_shipping_option": {
    },
  • "sender": {
    },
  • "session_id": "201cda14-975f-4c4d-9c2f-12f3896b5156"
}
Response samples
{
  • "additional_info": "string",
  • "selected_shipping_option": {
    },
  • "shipment_id": "c2059e35-58b1-4482-ad55-5e7ef541eae4",
  • "shipments": [
    ]
}

Confirm shipment reservation

This operation confirms the previously created shipment reservation (POST -> /shipment).

After the last POST /shipment or PUT /shipment/{id} call, one of two things can happen:

  • If the purchase goes through, this endpoint is called. The call is guaranteed to happen within an hour of the last call to POST /shipment or PUT /shipment/{id}. In most cases, the call to this endpoint will come within seconds.
  • If the purchase does not go through, this endpoint is never called. If an hour has passed since the last call to POST /shipment or PUT /shipment/{id}, it is safe to remove the reservation of the shipment.

A HTTP 401 error code will trigger an auth call. Any other HTTP response will be ignored as this is a best effort call without any possibility for consumer interaction.

Request
Security:
path Parameters
shipment_id
required
string

Unique shipment ID

header Parameters
Authorization
required
string <string>

Authorization token on format Bearer <token>.

Responses
200

Successful operation.

401

Invalid or expired token. A new token will be obtained.

post/shipment/{shipment_id}/confirm
Request samples
curl -i -X POST \
  'https://api.klarna.com/shipment/{shipment_id}/confirm' \
  -H 'Authorization: YOUR_API_KEY_HERE'