Introduction to the Shipping Service Callback API


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

The Integrator provides the business logic. KSS delegates the control of the business logic to the Integrator in just about all cases:

  • Configuration
    • Order-flow-path (see tags )
    • static configuration
  • Features
    • Pricing
    • Sorting
    • Filtering Anything in the order-flow-path can usually be supported with order or order line attributes, such as tags, weight, or dimensions.

The general flow of the API is as follows:

  • ‘’Authorization’’ : Klarna will use an aggregator specific merchant identifier and API key for authorization which are provided by the Merchant of Klarna and the Integrator. The Integrator will return a merchant unique token using a signed Json Web Token (JWT).
  • ‘’Get shipping options’’ : Klarna will fetch one or more times the shipping options with the ‘’get-shipping-options’’ call. The shipping options are authorized with the bearer token obtained from the auth call. The Integrator will return the available shipping options based on the Integrator own agreement with the merchant. Note that the merchant is liable for the use of any add-ons or badges offered within the Shipping Assistant, e.g. when marketing a specific shipping option as an express shipping method or as environmental friendly, and must ensure that the offered shipping method is compliant with the statement set out on the add-on/badge.
    • Shipping options should always be returned for partial address data - The minimum of recipient address data in a get-shipping-options request is country. If shipping is available in that country, a generic preview list of shipping options should be returned, a new call will be made when complete address data is available.
  • ‘’Select shipping options’’ : Klarna will select the preferred shipping option of the user with the ‘’select-shipping-options’’ call. This operation will confirm and save the selected shipping option. Klarna will enable the merchant to query and find the data in order to create a shipment of it. The select-shipping-options call happens at time of purchase (i.e when the user clicks buy).
    • If the call is successful, the Integrator will send a HTTP 201 response with a location header as a confirmation that the selected option is available, that the provided recipient data is valid and that the data has been saved successfully.
    • If the call is rejected, the Integrator will provide an error message. Klarna can display the error message to the user and restart the flow with the ‘’get-shipping-options’’ call. Klarna reserves the right to override the error message with custom copy as needed.
  • ‘’Get shipment’’ : Klarna can query the tracking number of the shipment.

Delivery Time Format

You can find the expected delivery time format in the Shipping Options.