openapi: 3.0.0
info:
  description: >-
    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/).
  title: Shipping Service Callback API
  version: 1.3.0
paths:
  /auth:
    post:
      requestBody:
        content:
          application/vdn.klarna.shipping.auth-v1+json:
            schema:
              $ref: '#/components/schemas/authorization_token_request'
        required: true
      responses:
        '201':
          description: Bearer token created successfully
          content:
            application/vdn.klarna.shipping.auth-v1+json:
              schema:
                $ref: '#/components/schemas/authorization_token_response'
        '400':
          description: >
            The /auth request was malformed. In order to simplify debugging,

            the field `failure_reason` should contain a text describing the
            failure reason.
          content:
            application/vdn.klarna.shipping.auth-v1+json:
              schema:
                $ref: '#/components/schemas/authentication_malformed_request'
        '401':
          description: Invalid or missing credentials
      description: "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).\r\n\r\nThe 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>`.\r\n\r\nMore about how this works:\r\n\r\nWhen 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:  \r\n```\r\nIdentifier: \"sweMerch123\"\r\nKey: \"smOOOth\"\r\n```\r\n\r\nAs 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.\r\n\r\nTo further the example, let's say KSS provided a Nonce of `'lRFUpqW7Xd'`:\r\n\r\n```\r\nNonce: \"lRFUpqW7Xd\"\r\nNonce+Key: \"lRFUpqW7XdsmOOOth\"\r\nDigest: \"8C3891B3162DB3AB61A9B2DA74E6A479553ABA897894E5236ED290C11A0B832B\"\r\n```\r\n\r\nThen KSS sends the authorization request with the Identifier, Nonce, and Digest.\r\n\r\nThe 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."
      operationId: auth
      summary: Get an authorization token
  /shippingoptions:
    post:
      parameters:
        - description: Authorization token on format `Bearer <token>`
          in: header
          name: Authorization
          required: true
          schema:
            type: string
            format: string
      requestBody:
        content:
          application/vdn.klarna.shipping.get_options-v1+json:
            schema:
              $ref: '#/components/schemas/get_shipping_options_request'
        required: true
      responses:
        '200':
          description: ''
          headers:
            Cache-Control:
              description: >
                Controls response caching, format: max-age=(seconds). Max time
                to cache response given the same input, the response will be
                re-used for up-to the given max-age. The default is no caching.

                Example: Cache-Control: max-age=60
              schema:
                type: string
          content:
            application/vdn.klarna.shipping.get_options-v1+json:
              schema:
                $ref: '#/components/schemas/get_shipping_options_response'
        '400':
          description: >
            The /shippingoptions request was malformed.

            In order to simplify debugging,

            the field `failure_reason` should contain a text describing the
            failure reason.
          content:
            application/vdn.klarna.shipping.get_options-v1+json:
              schema:
                $ref: '#/components/schemas/shipping_options_malformed_request'
        '401':
          description: Invalid or expired token. A new token will be obtained.
      security:
        - bearerAuth: []
      description: "Gets shipping options for the given customer data, address and order lines.\r\n\r\n>It's always important to display proper expected delivery date and time, to create a smoooth customer experience. Below\r\nyou can find a table with examples of how customer will see delivery date and time that is provided in the `delivery_time`\r\nfield of shipping option. Representation can vary in case provided date points to the same date or a period, in case the\r\ndate is today, tomorrow or any date in the future. Dates in the past are ignored.\r\n\r\n| Provided values | UI presentation | Examples |\r\n| --- | --- | --- |\r\n|  delivery_time.interval.earliest  | Delivered after `delivery_time.interval.earliest` business days | Delivered after 3 business days |\r\n|  delivery_time.interval.latest  | Delivered within `delivery_time.interval.latest` business days | Delivered within 3 business days |\r\n|  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 |\r\n|  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 |\r\n|  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 |\r\n|  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 |\r\n|  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 |\r\n|  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  |\r\n|  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 |\r\n|  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 |\r\n|  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 |\r\n|  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 |\r\n|  delivery_time.earliest  | Delivered `delivery_time.earliest` at the earliest |  Delivered tomorrow at the earliest Delivered Thursday March 5 at the earliest  |\r\n|  delivery_time.latest  | Delivered no later than `delivery_time.latest` |  Delivered today Delivered no later than tomorrow Delivered no later than Thursday, March 4  |\r\n|  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  |\r\n|  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  |\r\n|  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  |\r\n|  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  |\r\n|  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 |\r\n|  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 |\r\n|  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 |\r\n|  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 |\r\n|  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 |\r\n|  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  |"
      operationId: shippingoptions
      summary: List shipping options
  /shipment:
    post:
      parameters:
        - description: Authorization token on format `Bearer <token>`
          in: header
          name: Authorization
          required: true
          schema:
            type: string
            format: string
      requestBody:
        $ref: '#/components/requestBodies/select_shipping_option_request'
      responses:
        '200':
          description: Shipment reservation created and saved successfully
          headers:
            Location:
              description: >-
                Full URL to this shipment. E.g.
                https://example.com/shipment/c2059e35-58b1-4482-ad55-5e7ef541eae4
              schema:
                type: string
                format: uri
          content:
            application/vdn.klarna.shipping.select_shipment-v1+json:
              schema:
                $ref: '#/components/schemas/get_shipment'
            application/vdn.klarna.shipping.select_option-v1+json:
              schema:
                $ref: '#/components/schemas/get_shipment'
        '201':
          description: Shipment reservation created and saved successfully
          headers:
            Location:
              description: >-
                Full URL to this shipment. E.g.
                https://example.com/shipment/c2059e35-58b1-4482-ad55-5e7ef541eae4
              schema:
                type: string
                format: uri
          content:
            application/vdn.klarna.shipping.select_shipment-v1+json:
              schema:
                $ref: '#/components/schemas/get_shipment'
            application/vdn.klarna.shipping.select_option-v1+json:
              schema:
                $ref: '#/components/schemas/get_shipment'
        '400':
          description: >
            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.
          content:
            application/vdn.klarna.shipping.select_shipment-v1+json:
              schema:
                $ref: '#/components/schemas/select_shipping_option_failure_response'
            application/vdn.klarna.shipping.select_option-v1+json:
              schema:
                $ref: '#/components/schemas/select_shipping_option_failure_response'
        '401':
          description: Invalid or expired token. A new token will be obtained.
      security:
        - bearerAuth: []
      description: "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.\r\n\r\nThe shipment reservation should be unique per session_id provided in the request body.\r\n\r\nThis 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.\r\n\r\nA HTTP 4xx error code will interrupt the purchase flow and restart the shipping selection process. See `failure_reason`.\r\n\r\nIf the purchase is successfully completed, KSS will call `POST /shipment/{id}/confirm` to confirm the reservation. See the `/confirm` call.\r\n\r\nKSS 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."
      operationId: postshipment
      summary: Select shipping option
  /shipment/{shipment_id}:
    get:
      parameters:
        - description: Unique shipment ID.
          in: path
          name: shipment_id
          required: true
          schema:
            type: string
        - description: Authorization token on format `Bearer <token>`.
          in: header
          name: Authorization
          required: true
          schema:
            type: string
            format: string
      responses:
        '200':
          description: Successful operation.
          content:
            application/vdn.klarna.shipping.get_shipment-v1+json:
              schema:
                $ref: '#/components/schemas/get_shipment'
        '401':
          description: Invalid or expired token. A new token will be obtained.
        '404':
          description: No such shipment.
      security:
        - bearerAuth: []
      description: >-
        Get carrier product codes for the shipment, shipment status and optional
        carrier tracking data.
      operationId: getshipment
      summary: Get shipment status
    put:
      parameters:
        - description: Unique shipment ID
          in: path
          name: shipment_id
          required: true
          schema:
            type: string
        - description: Authorization token on format `Bearer <token>`.
          in: header
          name: Authorization
          required: true
          schema:
            type: string
            format: string
      requestBody:
        $ref: '#/components/requestBodies/select_shipping_option_request'
      responses:
        '200':
          description: Shipment reservation updated successfully.
          headers:
            Location:
              description: >-
                Full URL to this shipment. E.g.
                https://example.com/shipment/c2059e35-58b1-4482-ad55-5e7ef541eae4
              schema:
                type: string
                format: uri
          content:
            application/vdn.klarna.shipping.get_shipment-v1+json:
              schema:
                $ref: '#/components/schemas/get_shipment'
            application/vdn.klarna.shipping.select_option-v1+json:
              schema:
                $ref: '#/components/schemas/get_shipment'
        '400':
          description: >
            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.
          content:
            application/vdn.klarna.shipping.get_shipment-v1+json:
              schema:
                $ref: '#/components/schemas/select_shipping_option_failure_response'
            application/vdn.klarna.shipping.select_option-v1+json:
              schema:
                $ref: '#/components/schemas/select_shipping_option_failure_response'
        '401':
          description: Invalid or expired token. A new token will be obtained.
        '404':
          description: >-
            No such shipment (KSS will retry with a `POST /shipment` if this
            happens).
      security:
        - bearerAuth: []
      description: "This operation updates the previously created shipment reservation (`POST -> /shipment`).\r\n\r\nThe shipment reservation should be unique per session_id provided in the request body.\r\n\r\nThis 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.\r\n\r\nA 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.\r\n\r\nA HTTP 4xx error code will interrupt the purchase flow and restart the shipping selection process. See failure_reason."
      operationId: putshipment
      summary: Update the shipping option
  /shipment/{shipment_id}/confirm:
    post:
      parameters:
        - description: Unique shipment ID
          in: path
          name: shipment_id
          required: true
          schema:
            type: string
        - description: Authorization token on format `Bearer <token>`.
          in: header
          name: Authorization
          required: true
          schema:
            type: string
            format: string
      responses:
        '200':
          description: Successful operation.
        '401':
          description: Invalid or expired token. A new token will be obtained.
      security:
        - bearerAuth: []
      description: "This operation confirms the previously created shipment reservation (`POST -> /shipment`).\r\n\r\nAfter the last `POST /shipment` or `PUT /shipment/{id}` call, one of two things can happen:\r\n\r\n*   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.\r\n*   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.\r\n\r\nA 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."
      operationId: shipmentconfirm
      summary: Confirm shipment reservation
x-components: {}
servers:
  - url: https://api.klarna.co
components:
  requestBodies:
    select_shipping_option_request:
      content:
        application/vdn.klarna.shipping.select_option-v1+json:
          schema:
            $ref: '#/components/schemas/select_shipping_option_request'
      required: true
  securitySchemes:
    TMSAuth:
      type: http
      scheme: basic
    bearerAuth:
      in: header
      name: Authorization
      type: apiKey
  schemas:
    tags:
      description: >
        TMS defined order or order line attributes. The tags are passed in by
        the merchant during order creation and passed along as is.


        The TMS and Merchant use tags to direct custom business logic between
        themselves: (Note that these tags are examples and NOT required or
        related to KSS in any way)

        <ul>
          <li>Pricing</li>
            <ul>
              <li>`promo17`</li>
            </ul>
          <li>Option Configuration</li>
            <ul>
              <li>`next_day_only`</li>
              <li>`sort_by_cost_asc`</li>
              <li>`limit_8`</li>
            </ul>
          <li>Customer Metadata</li>
            <ul>
              <li>`member`</li>
              <li>`platinum`</li>
            </ul>
        </ul>


        Different tags are allowed on order and order line level.  For example,
        a merchant can provide order line detail of signifcance to the TMS, i.e.
        `["age_restricted","bulky"]`
      items:
        example: member
        type: string
      type: array
    addon_from_tms:
      description: Addons options allow the user to customize their shipment as desired.
      properties:
        id:
          description: >-
            Pass-through custom ID field set by the API provider. Can be used by
            the API provider to match add-ons in the `POST /shipment` request
            with add-ons from the `POST /shippingoptions` response.
          example: sms-pickup-point-3
          type: string
        max_length:
          description: >-
            Applies to text input add-ons. Maximum length of the text. If unset,
            no limit is applied.
          example: 4
          type: integer
        preselected:
          default: false
          description: >-
            If set to true, the add-on is selected by default (can be unselected
            by the user). Only applies to add-ons that are explicitly selectable
            (e.g., checkboxes and addresses, but not text inputs).
          type: boolean
        price:
          default: 0
          description: >-
            Additional cost in cents, including tax, that will be added to the
            option's price if the add-on is selected.
          example: 400
          type: integer
        required:
          default: false
          description: >-
            If true, the add-on is marked as mandatory and the user cannot
            finalize the purchase without selecting it or otherwise filling the
            required information.
          type: boolean
        type:
          //"description": >
            Each add-on type must appear at most once per shipping option. Type
            is one of: <ul>
              <li><b>sms</b>: Displays a checkbox and an input field for a phone number, for SMS notifications on delivery status updates.</li>
              <li><b>email</b>: Displays a checkbox and an input field for an email address, for email notifications on delivery status updates.</li>
              <li><b>floor-number</b>: Displays an input field where the consumer can provide the exact floor they live on within a building.</li>
              <li><b>apartment-number</b>: Displays an input field where the consumer can provide their exact apartment number for the courier.</li>
              <li><b>entry-code</b>: Displays an input field where the consumer can provide an entry code, e.g. for the building front door.</li>
              <li><b>locker-code</b>: Displays an input field where the consumer can provide a locker code, e.g. for the post box.</li>
              <li><b>additional-instructions</b>: Displays an input field where the consumer can provide additional delivery information for the courier.</li>
              <li><b>contactless-delivery</b>: Displays a checkbox for selecting a contactless delivery. Only available in the Nordics and Germany.</li>
              <li><b>leave-outside-door</b>: Displays a checkbox to allow the package to be left by the shopper's door if they are not home when it arrives. Only available in the Nordics and Germany.</li>
              <li><b>evening-delivery</b>: Displays a checkbox for selecting an evening delivery, between 1700 and 2200 on any of the delivery days.</li>
              <li><b>daytime-delivery</b>: Displays a checkbox for selecting a daytime delivery, between 0800 and 1700 on any of the delivery days.</li>
              <li><b>expedited-packing</b>: Displays a checkbox for selecting expedited packing. This represents a commitment from the merchant to prioritize this order within any warehouse handling or dispatchment processes.</li>
              <li><b>reusable-packaging</b>: Displays a checkbox for selecting reusable packaging. This represents a commitment from the merchant to send this order using reusable packaging.</li>
              <li><b>sustainable-packaging</b>: Displays a checkbox for selecting a sustainable packaging. This represents a commitment from the merchant to ensure the delivery uses easily recycleable or re-useable packaging.</li>
              <li><b>carbon-compensated</b>: Displays a checkbox for the user to make a carbon offsetting donation. Contact your Kustom account manager if you would like to explore this problem space further in partnership with us.</li>
              <li><b>indoor-home-delivery</b>: Displays a checkbox for selecting an indoor delivery, e.g. for large homewares or white goods.</li>
              <li><b>assembly-at-pickup</b>: Displays a checkbox for selecting assembly of the goods, e.g. for sports equipment like bikes or home and garden items.</li>
              <li><b>package-removal</b>: Displays a checkbox to allow the package to be removed by the merchant.</li>
            </ul>
          description: >
            Each add-on type must appear at most once per shipping option.


            Type is one of:


            - **sms**: Displays a checkbox and an input field for a phone
            number, for SMS notifications on delivery status updates.

            - **email**: Displays a checkbox and an input field for an email
            address, for email notifications on delivery status updates.

            - **floor-number**: Displays an input field where the consumer can
            provide the exact floor they live on within a building.

            - **apartment-number**: Displays an input field where the consumer
            can provide their exact apartment number for the courier.

            - **entry-code**: Displays an input field where the consumer can
            provide an entry code, e.g. for the building front door.

            - **locker-code**: Displays an input field where the consumer can
            provide a locker code, e.g. for the post box.

            - **additional-instructions**: Displays an input field where the
            consumer can provide additional delivery information for the
            courier.

            - **contactless-delivery**: Displays a checkbox for selecting a
            contactless delivery. Only available in the Nordics and Germany.

            - **leave-outside-door**: Displays a checkbox to allow the package
            to be left by the shopper's door if they are not home when it
            arrives. Only available in the Nordics and Germany.

            - **evening-delivery**: Displays a checkbox for selecting an evening
            delivery, between 17:00 and 22:00 on any of the delivery days.

            - **daytime-delivery**: Displays a checkbox for selecting a daytime
            delivery, between 08:00 and 17:00 on any of the delivery days.

            - **expedited-packing**: Displays a checkbox for selecting expedited
            packing. This represents a commitment from the merchant to
            prioritize this order within any warehouse handling or dispatch
            processes.

            - **reusable-packaging**: Displays a checkbox for selecting reusable
            packaging. This represents a commitment from the merchant to send
            this order using reusable packaging.

            - **sustainable-packaging**: Displays a checkbox for selecting
            sustainable packaging. This represents a commitment from the
            merchant to ensure the delivery uses easily recyclable or reusable
            packaging.

            - **carbon-compensated**: Displays a checkbox for the user to make a
            carbon offsetting donation. Contact your account manager if you
            would like to explore this area further in partnership with us.

            - **indoor-home-delivery**: Displays a checkbox for selecting an
            indoor delivery, e.g. for large homewares or white goods.

            - **assembly-at-pickup**: Displays a checkbox for selecting assembly
            of the goods, e.g. for sports equipment like bikes or home and
            garden items.

            - **package-removal**: Displays a checkbox to allow the package to
            be removed by the merchant.
          type: string
        url:
          description: >-
            Displays a 'Learn more' link to a web page with more information
            about the addon.
          example: https://www.kustom.co
          type: string
      required:
        - type
      type: object
    addon_user_data:
      description: Addons options allow the user to customize their shipment as desired.
      properties:
        data:
          description: Input from the user.
          properties:
            selected:
              //"description": >
                User selection with the following meaning depending on add-on
                type: <ul>
                  <li><b>sms</b>: Indicates whether or not the user wants SMS notifications.</li>
                  <li><b>email</b>: Indicates whether or not the user wants email notifications.</li>
                  <li><b>floor-number</b>: Should be ignored.</li>
                  <li><b>apartment-number</b>: Should be ignored.</li>
                  <li><b>entry-code</b>: Should be ignored.</li>
                  <li><b>locker-code</b>: Should be ignored.</li>
                  <li><b>additional-instructions</b>: Should be ignored.</li>
                  <li><b>contactless-delivery</b>: Indicates whether or not the user wants a contactless delivery.</li>
                  <li><b>leave-outside-door</b>: Indicates whether or not the user wants the package to be left by their door if they are not home when it arrives.</li>
                  <li><b>evening-delivery</b>: Indicates whether or not the user wants an evening delivery.</li>
                  <li><b>daytime-delivery</b>: Indicates whether or not the user wants a daytime delivery.</li>
                  <li><b>expedited-packing</b>: Indicates whether or not the user wants expedited packing.</li>
                  <li><b>sustainable-packaging</b>: Indicates whether or not the user wants sustainable packing.</li>
                  <li><b>carbon-compensated</b>: Indicates whether or not the user wants the shipment to be carbon compensated to the extent that is priced.</li>
                  <li><b>indoor-home-delivery</b>: Indicates whether or not the user wants an indoor delivery.</li>
                  <li><b>assembly-at-pickup</b>: Indicates whether or not the user wants the goods to be assembled at the pickup location.</li>
                  <li><b>package-removal</b>: Indicates whether or not the user wants the package to be removed by the merchant.</li>
                </ul>
              description: >
                User selection with the following meaning depending on add-on
                type:


                - **sms**: Indicates whether or not the user wants SMS
                notifications.

                - **email**: Indicates whether or not the user wants email
                notifications.

                - **floor-number**: Should be ignored.

                - **apartment-number**: Should be ignored.

                - **entry-code**: Should be ignored.

                - **locker-code**: Should be ignored.

                - **additional-instructions**: Should be ignored.

                - **contactless-delivery**: Indicates whether or not the user
                wants a contactless delivery.

                - **leave-outside-door**: Indicates whether or not the user
                wants the package to be left by their door if they are not home
                when it arrives.

                - **evening-delivery**: Indicates whether or not the user wants
                an evening delivery.

                - **daytime-delivery**: Indicates whether or not the user wants
                a daytime delivery.

                - **expedited-packing**: Indicates whether or not the user wants
                expedited packing.

                - **sustainable-packaging**: Indicates whether or not the user
                wants sustainable packaging.

                - **carbon-compensated**: Indicates whether or not the user
                wants the shipment to be carbon compensated to the extent that
                is priced.

                - **indoor-home-delivery**: Indicates whether or not the user
                wants an indoor delivery.

                - **assembly-at-pickup**: Indicates whether or not the user
                wants the goods to be assembled at the pickup location.

                - **package-removal**: Indicates whether or not the user wants
                the package to be removed by the merchant.
              type: boolean
            text:
              //"description": >
                User input with the following meaning depending on add-on type:
                <ul>
                  <li><b>sms</b>: Contains the phone number (non-empty if `selected` is true).</li>
                  <li><b>email</b>: Contains the email address (non-empty if `selected` is true).</li>
                  <li><b>floor-number</b>: Contains the input given by the user (can be empty).</li>
                  <li><b>apartment-number</b>: Contains the input given by the user (can be empty).</li>
                  <li><b>entry-code</b>: Contains the input given by the user (can be empty).</li>
                  <li><b>locker-code</b>: Contains the input given by the user (can be empty).</li>
                  <li><b>additional-instructions</b>: Contains the input given by the user (can be empty).</li>
                  <li><b>contactless-delivery</b>: Should be ignored.
                  <li><b>leave-outside-door</b>: Should be ignored.
                  <li><b>evening-delivery</b>: Should be ignored.
                  <li><b>daytime-delivery</b>: Should be ignored.
                  <li><b>expedited-packing</b>: Should be ignored.
                  <li><b>sustainable-packaging</b>: Should be ignored.
                  <li><b>carbon-compensated</b>: Should be ignored.
                  <li><b>indoor-home-delivery</b>: Should be ignored.
                  <li><b>assembly-at-pickup</b>: Should be ignored.
                  <li><b>package-removal</b>: Should be ignored.
                </ul>
              description: >
                User input with the following meaning depending on add-on type:


                - **sms**: Contains the phone number (non-empty if `selected` is
                true).

                - **email**: Contains the email address (non-empty if `selected`
                is true).

                - **floor-number**: Contains the input given by the user (can be
                empty).

                - **apartment-number**: Contains the input given by the user
                (can be empty).

                - **entry-code**: Contains the input given by the user (can be
                empty).

                - **locker-code**: Contains the input given by the user (can be
                empty).

                - **additional-instructions**: Contains the input given by the
                user (can be empty).

                - **contactless-delivery**: Should be ignored.

                - **leave-outside-door**: Should be ignored.

                - **evening-delivery**: Should be ignored.

                - **daytime-delivery**: Should be ignored.

                - **expedited-packing**: Should be ignored.

                - **sustainable-packaging**: Should be ignored.

                - **carbon-compensated**: Should be ignored.

                - **indoor-home-delivery**: Should be ignored.

                - **assembly-at-pickup**: Should be ignored.

                - **package-removal**: Should be ignored.
              type: string
          type: object
        id:
          description: The `id` value from the `POST /shippingoptions` response.
          example: sms-pickup-point-3
          type: string
        max_length:
          description: The `max_length` value from the `POST /shippingoptions` response.
          example: 4
          type: integer
        preselected:
          description: The `preselected` value from the `POST /shippingoptions` response.
          type: boolean
        price:
          description: The `price` value from the `POST /shippingoptions` response.
          example: 400
          type: integer
        required:
          description: The `required` value from the `POST /shippingoptions` response.
          type: boolean
        type:
          description: >-
            The `type` value from the `POST /shippingoptions` response. Type is
            one of:
          enum:
            - sms
            - email
            - floor-number
            - apartment-number
            - entry-code
            - locker-code
            - additional-instructions
            - contactless-delivery
            - leave-outside-door
            - evening-delivery
            - daytime-delivery
            - expedited-packing
            - sustainable-packaging
            - carbon-compensated
            - indoor-home-delivery
            - assembly-at-pickup
            - package-removal
          type: string
      required:
        - type
        - data
        - id
      type: object
    address:
      properties:
        city:
          example: Stockholm
          type: string
        country:
          description: 2 character ISO 3166 country format
          example: SE
          type: string
        postal_code:
          description: Normalized to country specifications
          example: 111 34
          type: string
        region:
          description: Country specific region
          example: CA
          type: string
        street_address:
          example: Sveavägen 46
          type: string
        street_address2:
          type: string
      required:
        - street_address
        - postal_code
        - city
        - country
      type: object
    area:
      description: >-
        DRAFT - Geographically enclosed delivery area. WIP: Specifications might
        change.
      properties:
        boundary:
          description: >-
            Polygon definition of enclosed area using decimal degree
            geographical coordinates
          example:
            - lat: 18.062689527869225
              lng: 59.33655850186736
            - lat: 18.063891157507896
              lng: 59.336892270502865
            - lat: 18.06284509599209
              lng: 59.33791817815379
            - lat: 18.061750754714012
              lng: 59.337655548745
          items:
            $ref: '#/components/schemas/coordinates'
          type: array
        price:
          description: >-
            Price in cents including tax for this area, if different from base
            price. Tax rate from base price.
          example: 5000
          type: integer
        type:
          description: The type of area enclosed by the boundaries
          enum:
            - archipelago
            - urban
            - suburban
            - rural
          example: archipelago
          type: string
      required:
        - type
        - boundary
      type: object
    authentication_malformed_request:
      properties:
        failure_reason:
          example: '''example123'' is not a valid user identifier'
          type: string
    authorization_token_request:
      description: >
        Merchant authentication data for authorizing at the TMS. The credentials
        consist of an identifier and an API-key, both are configured by the
        merchant in Kustoms systems.

        The identifier is treated as a string and should contain enough
        information to identify the merchant at the TMS and any specific
        configuration or profile needed.

        There should be different credentials for test/playground and production
        environments.

        API key/credentials for access to TMS is hashed using SHA-256 together
        with a random nonce.
      properties:
        identifier:
          description: >-
            Handled as a string. Should uniquely identify the merchant at the
            TMS and any configuration if different profiles are available.
          example: merchant-12345-profile-65432
          type: string
        secret:
          description: API key/credentials for to authorize the merchant
          properties:
            digest:
              description: >-
                sha-256 digest over nonce and merchant API key. Format
                `sha256(nonce+key)`
              example: 8C3891B3162DB3AB61A9B2DA74E6A479553ABA897894E5236ED290C11A0B832B
              type: string
            nonce:
              example: lRFUpqW7Xd
              type: string
      type: object
    authorization_token_response:
      properties:
        token:
          description: >-
            Authorization token, will be used as bearer. Recommended
            implementation using JWT 
          example: >-
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudCI6ImZvb2JhciJ9.k2tE6vdJAEGbYSeZj2YluRK5vZbPAxsjd7XqARpBX3Y
          type: string
      type: object
    carrier:
      description: |
        Transportation carrier company used.
        <ul>
          <li><b>merchant</b> can be used for merchant self-hosted delivery methods (ex. instore pickup).</li>
          <li><b>generic-postal</b> can be used to indicate a generic postal network.</li>
          <li>Additional carriers can be supported on request.</li>
        </ul>
        Value should be one of:
      enum:
        - acs-courier
        - airmee
        - an-post
        - asendia
        - australia-post
        - austrian-post
        - bartolini
        - best
        - bpost
        - bring
        - bring-green
        - budbee
        - budbee-box
        - budcompaniett
        - bussgods
        - citymail
        - colis-prive
        - colissimo
        - collicare
        - correos
        - correos-express
        - crown-relocations
        - czech-post
        - dachser
        - danske-fragt
        - dao
        - deutsche-post
        - dhl
        - dhl-express
        - doorier
        - dooris
        - dpd
        - dsv
        - dynalogic
        - e2y
        - early-bird
        - emily-company
        - evri
        - fedex
        - fietskoeriers
        - generic
        - generic-postal
        - gls
        - gordon
        - helthjem
        - hoekstra
        - hrvatska-posta
        - in-time
        - instabikes
        - instabox
        - instabox-green
        - itella
        - kaukokiito
        - kiitolinja
        - laposte
        - leen-merken
        - lgt
        - magyar-posta
        - mat-se
        - matkahuolto
        - merchant
        - mioo-assembly-service
        - mx-transport
        - mondial-relay
        - mtd
        - netflux
        - ntex
        - oda
        - omniva
        - onroad
        - paack
        - packs
        - porterbuddy
        - post-it
        - post-luxembourg
        - posta-slovenija
        - posten-norge
        - posti
        - postnl
        - postnl-extra-home
        - postnord
        - professional-parcel-logistic
        - quick-pac
        - rapido
        - red-je-pakketje
        - relais-colis
        - royal-mail
        - safe-carrier-logistics
        - sagawa
        - schenker
        - skargarda
        - slovenska-posta
        - stuart
        - svosj
        - svosj-trial
        - swiss-post
        - swoopin
        - trunkrs
        - ups
        - urbit
        - urgent-cargus
        - van-spreuwel
        - wideroe-smart
        - wolt
        - yunda
        - zalando
      example: postnord
      type: string
    coordinates:
      description: Geographical position in decimal degrees
      properties:
        lat:
          description: Latitude in decimal degrees
          example: 59.336946
          type: number
        lng:
          description: Longitude in decimal degrees
          example: 18.063095
          type: number
      required:
        - lat
        - lng
      type: object
    delivery_time:
      description: >-
        Defines earliest and latest estimated delivery dates and/or times and
        the cutoff time for these delivery times to be met. Is used to indicate
        estimated delivery time to the user. Timezone should be given if time is
        supplied, otherwise zulu is assumed.



        NOTE: The *interval* object always overrides the explicit earliest and
        latest delivery dates (which means these will be ignored if an
        *interval* is set).
      properties:
        cutoff:
          description: >-
            Delivery times are only valid if order is placed before this time,
            in ISO 8601 format.
          example: '2017-07-21T17:32:28Z'
          format: date-time
          type: string
        earliest:
          description: Earliest possible delivery date, in ISO 8601 format.
          example: '2017-07-21T17:32:28Z'
          format: date-time
          type: string
        interval:
          description: >-
            Defines offsets for earliest and latest estimated delivery dates, in
            business days. Timezone offset should be given in terms of UTC
            offset in seconds (see utc_offset_in_seconds), otherwise 0 is
            assumed.
          properties:
            earliest:
              description: >-
                Date offset (in business days) that will be added to current
                local time in UTC and be presented as a delivery_time earliest
                date.
              example: '3'
              type: string
            latest:
              description: >-
                Date offset (in business days) that will be added to current
                local time in UTC and be presented as a delivery_time latest
                date.
              example: '5'
              type: string
            utc_offset_in_seconds:
              description: >-
                The UTC offset (in seconds) that will be used when formatting
                the evaluated date/time.
              example: '3600'
              type: string
        latest:
          description: Parcel will be delivered at latest this date, in ISO 8601 format.
          example: '2017-07-21T17:32:28Z'
          format: date-time
          type: string
        time_of_day:
          description: Defines earliest and latest estimated delivery times of day.
          properties:
            earliest:
              description: >-
                Defines earliest estimated delivery time in ISO 8601 format. The
                date part will be ignored.
              example: '2017-07-21T17:32:28Z'
              format: date-time
              type: string
            latest:
              description: >-
                Defines latest estimated delivery time in ISO 8601 format. The
                date part will be ignored.
              example: '2017-07-21T19:32:28Z'
              format: date-time
              type: string
      type: object
    dimensions:
      description: Dimensions of this item
      properties:
        height:
          description: height in mm
          example: 5000
          type: integer
        length:
          description: length in mm
          example: 5000
          type: integer
        width:
          description: width in mm
          example: 5000
          type: integer
      type: object
    feature:
      description: >-
        Non-actionable feature description or piece of information. Enhances
        option display without allowing user input.
      properties:
        class:
          description: >-
            Determines if the feature is an simple information box or a badge.
            Badges are eye-catching and colourful, highlighting a particular
            feature of the shipping option to draw the shopper's attention.
          enum:
            - info
            - badge
            - call_to_action
          type: string
        merchant_info_text:
          description: >-
            Text to be displayed in the info-box. Only applicable when `type` is
            `merchant_info_text`.
          type: string
        type:
          description: |
            This string will determine the feature applied. Info-boxes:
              <ul>
                <li><b>distributor-will-contact</b>: Displays an info-box to say the distributor will contact the shopper afterwards.</li>
                <li><b>package-removal</b>: Displays an info-box to say the carrier will remove the packaging and dispose of it on behalf of the shopper.</li>
                <li><b>room-delivery</b>: Displays an info-box to say the order will be delivered and carried into the room of the shopper's choice.</li>
                <li><b>delivery-time-extra-info</b>: Displays an info-box to say the stated number of days refers to the shipping time from the merchant to the consumer.</li>
                <li><b>multiple-deliveries-info</b>: Displays an info-box to say that the order will be split into multiple deliveries.</li>
                <li><b>merchant-info-text</b>: Displays an info-box with the text provided in <code>merchant_info_text</code></li>
              </ul>
              Badges:
              <ul>
                <li><b>afternoon</b>: Displays a badge highlighting that the option is an afternoon delivery option.</li>
                <li><b>carbon-compensated</b>: Displays a badge highlighting that the option will be carbon compensated.</li>
                <li><b>eco-friendly</b>: Displays a badge highlighting that the option is environmentally friendly.</li>
                <li><b>evening</b>: Displays a badge highlighting that the option is an evening delivery option.</li>
                <li><b>express</b>: Displays a badge highlighting that the option is an express option.</li>
                <li><b>fossil-free</b>: Displays a badge highlighting that the shipping option is fossil free.</li>
                <li><b>in-door-home-delivery</b>: Displays a badge highlighting that the shipment will be delivered indoors.</li>
                <li><b>morning</b>: Displays a badge highlighting that the option is a moning delivery option.</li>
                <li><b>multiple-deliveries</b>: Displays a badge highlighting that the shipment will be split into multiple deliveries.</li>
                <li><b>outdoor-home-delivery</b>: Displays a badge highlighting that the shipment will be delivered outdoors.</li>
                <li><b>recommended</b>: Displays a badge highlighting that the option recommended by the merchant.</li>
                <li><b>traceable</b>: Displays a badge highlighting that the shipping option is traceable.</li>
              </ul>
              Call to actions:
              <ul>
                <li><b>learn-more</b>: Displays a 'Learn more' link to a URL with more information about the feature.</li>
                <li><b>size-guide</b>: Displays a 'Size Guide' icon that links to URL with a size guide.</li>
              </ul>
          type: string
        url:
          description: >-
            Displays a link to a web page with information about the feature.
            Only applicable when `class` is `call_to_action`.
          example: https://www.kustom.co
          type: string
      required:
        - type
    get_shipment:
      properties:
        additional_info:
          description: >-
            Any additional information that should be passed to a merchant from
            TMS can be provided here. Limit is 256 characters.
          type: string
        selected_shipping_option:
          properties:
            carrier:
              $ref: '#/components/schemas/carrier'
            carrier_product:
              properties:
                addon_identifiers:
                  description: Product addon identifiers
                  items:
                    example: '1'
                    type: string
                  type: array
                identifier:
                  description: Carrier identifier/product code
                  example: '19'
                  type: string
                name:
                  description: Carrier product name
                  example: MyPack
                  type: string
              type: object
          required:
            - carrier
          type: object
        shipment_id:
          description: The id of the (reserved) shipment
          example: c2059e35-58b1-4482-ad55-5e7ef541eae4
          type: string
        shipments:
          items:
            properties:
              carrier:
                $ref: '#/components/schemas/carrier'
              tracking_id:
                description: Carrier-specific tracking id.
                type: string
              tracking_url:
                description: >-
                  Carrier-specific URL to a web page where the consumer can see
                  and make changes to their delivery.
                type: string
            type: object
          type: array
      required:
        - shipment_id
        - selected_shipping_option
      type: object
    get_shipping_options_request:
      properties:
        currency:
          description: ISO 4217 alphabetic currency code.
          example: SEK
          type: string
        geoblocking:
          description: >
            A flag that indicates if the requested shipping options are for
            geoblocking flow.

            <p>
              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”.
            </p>

            <p>
              User Flows:
              <ol type="1">
                <li>A Norwegian consumer enters abc.se</li>
                <li>The consumer selects Norway as billing country and fills in his/her address</li>
                <li>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.”</li>
                <li>The consumer chooses the delivery country (only if more than one is available).
                    <ol type="i">
                      <li>The consumer either fills in an address and gets a full set of shipping options <b>OR</b></li>
                      <li>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.</li>
                    </ol>
                </li>
              </ol>
            </p>
          example: true
          type: boolean
        locale:
          description: IETF BCP-47 locale definition.
          example: sv-SE
          format: lc-CC
          type: string
        order:
          $ref: '#/components/schemas/order'
        recipient:
          $ref: '#/components/schemas/recipient'
        selected_shipping_option_id:
          description: >
            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.
          example: tms-specific-shipping-option-id
          type: string
        sender:
          $ref: '#/components/schemas/sender'
        session_id:
          description: Unique Kustom shipping session id.
          example: 201cda14-975f-4c4d-9c2f-12f3896b5156
          type: string
      required:
        - session_id
        - locale
        - currency
        - recipient
        - order
      type: object
    get_shipping_options_response:
      properties:
        shipping_options:
          items:
            $ref: '#/components/schemas/shipping_option'
          type: array
      type: object
    location:
      description: >-
        A location describes a pickup location, either a pickup-point, box or
        store. Coordinates are optional, if not supplied KSS will attempt to use
        geolocation based on the address.
      properties:
        address:
          $ref: '#/components/schemas/address'
        coordinates:
          $ref: '#/components/schemas/coordinates'
        delivery_time:
          $ref: '#/components/schemas/delivery_time'
        id:
          description: Optional TMS provided identifier, will be passed back if provided.
          example: loc-12345
          type: string
        name:
          description: User friendly name of location (pickup point, store name, etc).
          example: ICA supermarket
          type: string
        operational_hours:
          $ref: '#/components/schemas/operational_hours'
        price:
          description: >-
            Price in cents including tax for this location, if different from
            base price. Tax rate from base price.
          example: 0
          type: integer
      required:
        - name
        - address
      type: object
    open_hours:
      description: >-
        Opening and closing times for (part of) a given day (24 hs Format. e.g.
        '09:00', '18:00'). Assumes local timezone.
      properties:
        always_open:
          default: false
          description: Open all day
          type: boolean
        close:
          description: 24 hs Format (e.g. 18:00)
          example: '22:00'
          type: string
        closed:
          default: false
          description: Closed all day
          type: boolean
        open:
          description: 24 hs Format (e.g. 09:00)
          example: '09:00'
          type: string
      type: object
    operational_hours:
      description: >-
        Opening and closing times for a location (24 hs Format. e.g. '09:00',
        '18:00'). If operational hours are unknown, do not provide this object.
        Otherwise, provide hours or an open/closed status for each day, either
        using default hours or providing overrides for each day of the week.
      properties:
        default:
          description: >-
            Opening and closing hours (24 hs Format. e.g. '09:00', '18:00') *OR*
            an open/closed status for each day of the week
          items:
            $ref: '#/components/schemas/open_hours'
          type: array
        overrides:
          properties:
            date:
              items:
                properties:
                  date:
                    example: '2017-12-24'
                    format: date
                    type: string
                  hours:
                    $ref: '#/components/schemas/open_hours'
                type: object
              type: array
            weekday:
              properties:
                fri:
                  items:
                    $ref: '#/components/schemas/open_hours'
                  type: array
                mon:
                  items:
                    $ref: '#/components/schemas/open_hours'
                  type: array
                sat:
                  items:
                    $ref: '#/components/schemas/open_hours'
                  type: array
                sun:
                  items:
                    $ref: '#/components/schemas/open_hours'
                  type: array
                thu:
                  items:
                    $ref: '#/components/schemas/open_hours'
                  type: array
                tue:
                  items:
                    $ref: '#/components/schemas/open_hours'
                  type: array
                wed:
                  items:
                    $ref: '#/components/schemas/open_hours'
                  type: array
      type: object
    order:
      description: Order definition
      properties:
        tags:
          $ref: '#/components/schemas/tags'
        id:
          description: >-
            Kustom order id, will be known at time of purchase and only provided
            in the `/shipment` call. No assumption should be made about the
            format.
          type: string
        lines:
          items:
            $ref: '#/components/schemas/order_lines'
          type: array
        total_amount:
          description: Total order amount including tax in cents.
          example: 10000
          type: integer
        total_tax:
          description: Total tax of the order amount in cents.
          example: 2500
          type: integer
        total_weight:
          description: Total weight in grams
          example: 2000
          type: integer
      required:
        - total_amount
        - total_tax
        - lines
      type: object
    order_line_attributes:
      properties:
        tags:
          $ref: '#/components/schemas/tags'
        dimensions:
          $ref: '#/components/schemas/dimensions'
        weight:
          description: Weight of this item in grams
          example: 1000
          type: integer
      type: object
    order_lines:
      description: Rich order line information
      properties:
        attributes:
          $ref: '#/components/schemas/order_line_attributes'
        quantity:
          example: 2
          type: integer
        reference:
          description: Merchant provided item reference
          example: sku-1234
          type: string
        tax_rate:
          description: >-
            Tax rate of shipping option in percent. Non-negative, two implicit
            decimals. I.e 2500 = 25.00%.
          example: 2500
          type: integer
        total_discount_amount:
          description: Total discount amount in cents
          example: 1000
          type: integer
        total_price_including_tax:
          description: Total price of items, including tax, given in cents
          example: 4000
          type: integer
        total_tax_amount:
          description: Total tax amount in cents
          example: 1250
          type: integer
        type:
          description: Order line type.
          enum:
            - physical
            - discount
            - shipping_fee
            - sales_tax
            - digital
            - gift_card
            - store_credit
            - surcharge
          type: string
        unit_price:
          description: Unit price in cents
          example: 2500
          type: integer
      required:
        - quantity
        - unit_price
        - tax_rate
        - total_tax_amount
        - total_price_including_tax
      type: object
    recipient:
      description: Information about the recipient
      properties:
        care_of:
          type: string
        city:
          example: Stockholm
          type: string
        company_name:
          description: Applicable only if recipient is a company
          example: Kustom AB
          type: string
        country:
          description: 2 character ISO 3166 country format
          example: SE
          type: string
        customer_type:
          description: >-
            B2C or B2B customer type. Note: does only indicate the type of
            customer, not if the address is residential or business.
          enum:
            - person
            - organization
          type: string
        email:
          example: info@kustom.com
          type: string
        family_name:
          example: Joyce
          type: string
        given_name:
          example: Klara
          type: string
        phone:
          description: E.164 international format
          example: '+46812012010'
          type: string
        postal_code:
          description: Normalized to country specifications
          example: 111 34
          type: string
        region:
          description: Country specific region
          example: CA
          type: string
        street_address:
          example: Sveavägen 46
          type: string
        street_address2:
          type: string
      required:
        - country
      type: object
    select_shipping_option_failure_response:
      description: Reason the shipment reservation couldn't be created
      properties:
        failure_reason:
          example: shipping_option_not_available
          type: string
      type: object
    select_shipping_option_request:
      properties:
        currency:
          description: ISO 4217 alphabetic currency code
          example: SEK
          type: string
        locale:
          description: IETF BCP-47 locale definition
          example: sv-SE
          format: lc-CC
          type: string
        order:
          $ref: '#/components/schemas/order'
        recipient:
          allOf:
            - $ref: '#/components/schemas/recipient'
            - required:
                - given_name
                - family_name
                - street_address
                - postal_code
                - city
        selected_shipping_option:
          properties:
            addons:
              items:
                $ref: '#/components/schemas/addon_user_data'
              type: array
            carrier:
              description: The carrier for this option
              example: dhl
              type: string
            class:
              description: The shipping class for this option
              example: express
              type: string
            id:
              description: Optional TMS provided identifier
              example: option-1234
              type: string
            location:
              properties:
                address:
                  $ref: '#/components/schemas/address'
                coordinates:
                  $ref: '#/components/schemas/coordinates'
                id:
                  description: Optional TMS provided identifier
                  example: location-1234
                  type: string
                name:
                  description: Name of location
                  example: ICA Supermarket
                  type: string
              type: object
            price:
              description: Total price for this option in cents, including extras and tax
              example: 2500
              type: integer
            tax_rate:
              description: Tax rate of shipping option.
              example: 2500
              type: integer
            timeslot:
              properties:
                end:
                  description: End of timeslot in ISO 8601 format
                  format: date-time
                  type: string
                id:
                  description: Optional TMS provided identifier
                  example: timeslot-1234
                  type: string
                start:
                  description: Start of timeslot in ISO 8601 format
                  format: date-time
                  type: string
              required:
                - start
                - end
              type: object
            type:
              description: The type of shipping option
              example: delivery-address
              type: string
          required:
            - id
          type: object
        sender:
          $ref: '#/components/schemas/sender'
        session_id:
          description: Unique Kustom shipping session id.
          example: 201cda14-975f-4c4d-9c2f-12f3896b5156
          type: string
      required:
        - session_id
        - locale
        - currency
        - recipient
        - selected_shipping_option
      type: object
    sender:
      description: >-
        Information about the sender. Should indicate from where the goods are
        dispatched. This object is optional and can be empty.
      properties:
        address:
          $ref: '#/components/schemas/address'
        sender_id:
          description: >-
            Optional merchant provided sender identifier. Can be used to
            identify different warehouses within the same country or different
            dispatch routes that can affect delivery time.
          example: warehouse-13
          type: string
      type: object
    shipping_option:
      properties:
        addons:
          items:
            $ref: '#/components/schemas/addon_from_tms'
          type: array
        area:
          $ref: '#/components/schemas/area'
        carrier:
          $ref: '#/components/schemas/carrier'
        class:
          default: standard
          description: |
            Description:
            <ul>
              <li><b>standard</b>: Normal delivery time.</li>
              <li><b>economy</b>: Slow delivery.</li>
              <li><b>express</b>: Fast delivery.</li>
              <li><b>courier</b>: Fastest delivery time, like food delivery.</li>
            </ul>
            Value should be one of:
          enum:
            - standard
            - economy
            - express
            - courier
          type: string
        delivery_time:
          $ref: '#/components/schemas/delivery_time'
        features:
          items:
            $ref: '#/components/schemas/feature'
          type: array
        free_above:
          description: >-
            The total amount threshold at which the shipping option price
            becomes free, i.e. 0.00. In cents, i.e. 10000 = 100.00.
          example: 10000
          type: integer
        id:
          description: Aggregator provided identifier. Must be unique.
          example: option-1234
          type: string
        locations:
          description: Location definitions of pickup points/boxes, store locations, etc.
          items:
            $ref: '#/components/schemas/location'
          type: array
        name:
          description: >-
            Carrier product name. Will only be used as a fallback in case Kustom
            does not have a proper copy string for the shipping option.
          example: FedEx Priority
          type: string
        preview:
          description: >-
            Should be set to true if this option was included as a result of
            partial address data and that it might be changed or removed when
            full address data is available.
          example: false
          type: boolean
        price:
          description: Price of shipping option in cents including tax. I.e. 4000 = 40.00.
          example: 4000
          type: integer
        tax_rate:
          description: >-
            Tax rate of shipping option in percent. Non-negative, two implicit
            decimals. I.e 2500 = 25.00%. The amount of tax will be calculated as
            price - (price * 10000 / (10000 + tax_rate)).
          example: 2500
          type: integer
        timeslots:
          description: >-
            Timeslot definition, only applicable to delivery methods with
            timeslots.
          items:
            $ref: '#/components/schemas/timeslot'
          type: array
        type:
          description: |
            <ul>
              <li><b>boat-delivery</b>: Delivery by boat.</li>
              <li><b>click-collect</b>: Order goods online for reservation and pick up at a merchant store.</li>
              <li><b>delivery-address</b>: To address/door delivery, final selected option will contain an address and potential timeslot.</li>
              <li><b>generic-pickup</b>: Delivery to a pickup point when location is unknown.</li>
              <li><b>generic-shipping</b>: Shipping option when the carrier decides shipping method.</li>
              <li><b>office-delivery</b>: Delivery to an office address. For eg. to an office reception.</li>
              <li><b>pallet-delivery</b>: Home delivery of big/heavy goods by truck and on a pallet.</li>
              <li><b>crane-delivery</b>: Delivery by crane for very large goods, such as pools and jacuzzis.</li>
              <li><b>pickup-box</b>: Delivery to a pickup locker/box. Final selected option will contain a location.</li>
              <li><b>pickup-merchant-store</b>: Delivery to a merchant store for pickup. Final selected option will contain a location.</li>
              <li><b>pickup-point</b>: Delivery to a pickup point. Final selected option will contain a location.</li>
              <li><b>pickup-warehouse</b>: Delivery to a merchant warehouse for pick up.</li>
              <li><b>postal</b>: Best-effort delivery of a package/letter using the postal network.</li>
            </ul>
          example: pickup-point
          type: string
      required:
        - id
        - type
        - carrier
        - price
        - tax_rate
      type: object
    shipping_options_malformed_request:
      properties:
        failure_reason:
          example: Field 'xxx.yyy.example' must not be empty.
          type: string
    timeslot:
      description: >-
        Delivery timeslot definition. A timeslot is a range of time at which a
        parcel will be delivered, it can be day slots and/or time slots with
        minute precision. Timeslots can be overlapping.
      properties:
        cutoff:
          description: Timeslot only valid if order is placed before this time
          example: '2017-07-21T17:32:28Z'
          format: date-time
          type: string
        end:
          description: End time of slot in ISO 8601 format
          example: '2017-07-21T17:32:28Z'
          format: date-time
          type: string
        id:
          description: Optional TMS provided identifier, will be passed back if provided
          example: slot-12345
          type: string
        price:
          description: >-
            Price in cents including tax for this slot, if different from base
            price. Tax rate from base price.
          example: 0
          type: integer
        start:
          description: Start time of slot in ISO 8601 format
          example: '2017-07-21T17:32:28Z'
          format: date-time
          type: string
      required:
        - start
        - end
      type: object
