# Shipping Service Callback API The Shipping Service Callback API enables communication between the Shipping Service and the Integrator. Read more on [Shipping assistant](https://docs.klarna.com/shipping-assistant/). Version: 1.3.0 ## Servers ``` https://api.klarna.co ``` ## Security ### TMSAuth Type: http Scheme: basic ### bearerAuth Type: apiKey In: header Name: Authorization ## Download OpenAPI description [Shipping Service Callback API](https://docs.kustom.co/_bundle/contents/api/shipping-service-callback.yaml) ## Other ### Get an authorization token - [POST /auth](https://docs.kustom.co/contents/api/shipping-service-callback/other/auth.md): 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 . 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 Kustom 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. ### List shipping options - [POST /shippingoptions](https://docs.kustom.co/contents/api/shipping-service-callback/other/shippingoptions.md): 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 | ### Select shipping option - [POST /shipment](https://docs.kustom.co/contents/api/shipping-service-callback/other/postshipment.md): 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. ### Get shipment status - [GET /shipment/{shipment_id}](https://docs.kustom.co/contents/api/shipping-service-callback/other/getshipment.md): Get carrier product codes for the shipment, shipment status and optional carrier tracking data. ### Update the shipping option - [PUT /shipment/{shipment_id}](https://docs.kustom.co/contents/api/shipping-service-callback/other/putshipment.md): 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. ### Confirm shipment reservation - [POST /shipment/{shipment_id}/confirm](https://docs.kustom.co/contents/api/shipping-service-callback/other/shipmentconfirm.md): 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.