openapi: 3.0.0
info:
  description: >-
    Kustom provides a number of different callbacks during the customer's
    checkout session. The callbacks can be used to update the order when the
    customer changes their address as well as to do a final check to validate
    the order before it is submitted. The callbacks are sent as POST requests to
    the endpoint you specify when creating the order. Your response is
    interpreted using the response code and body.
  version: 1.0.0
  title: Checkout callback
paths:
  /merchant_urls.address_update:
    post:
      summary: Address update
      description: >-
        Will be called whenever the consumer changes  billing or shipping
        address. The order will be updated according to the response received by
        Checkout.
      operationId: updateAddress
      requestBody:
        $ref: '#/components/requestBodies/shipping_service_request'
      responses:
        '200':
          description: >-
            Address looks good. The order will be updated according to response
            data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipping_service_response'
        '301':
          description: >-
            Bad Address. Checkout will redirect the consumer to the page in
            Location header value.
          headers: {}
        '302':
          description: >-
            Bad Address. Checkout will redirect the consumer to the page in
            Location header value.
          headers: {}
        '303':
          description: >-
            Bad Address. Checkout will redirect the consumer to the page in
            Location header value.
          headers: {}
        '307':
          description: >-
            Bad Address. Checkout will redirect the consumer to the page in
            Location header value.
          headers: {}
        '400':
          description: >-
            Bad address. This type of response can be used to show an error text
            message to the consumer. The response body should include one of the
            following values in the error_type field: 'address_error',
            'unsupported_shipping_address' or 'approval_failed'. An 'error_text'
            field can also be included in the response (mandatory if error_type
            is 'address_error' or 'approval_failed'). The error message will be
            shown to the consumer and he or she will be kept in the Checkout
            page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipping_service_error_response'
  /merchant_urls.country_change:
    post:
      summary: Country change
      description: >-
        Will be called whenever the consumer changes  billing address country.
        The order will be updated according to the response received by
        Checkout.
      operationId: countryChange
      requestBody:
        $ref: '#/components/requestBodies/shipping_service_request'
      responses:
        '200':
          description: >-
            New country is accepted. The order will be updated according to
            response data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipping_service_response'
        '301':
          description: >-
            New country is not accepted. Checkout will redirect the consumer to
            the page in Location header value.
          headers: {}
        '302':
          description: >-
            New country is not accepted. Checkout will redirect the consumer to
            the page in Location header value.
          headers: {}
        '303':
          description: >-
            New country is not accepted. Checkout will redirect the consumer to
            the page in Location header value.
          headers: {}
        '307':
          description: >-
            New country is not accepted. Checkout will redirect the consumer to
            the page in Location header value.
          headers: {}
        '400':
          description: >-
            Bad address. This type of response can be used to show an error text
            message to the consumer. The response body should include one of the
            following values in the error_type field: 'address_error',
            'unsupported_shipping_address' or 'approval_failed'. An 'error_text'
            field can also be included in the response (mandatory if error_type
            is 'address_error' or 'approval_failed'). The error message will be
            shown to the consumer and he or she will be kept in the Checkout
            page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipping_service_error_response'
  /merchant_urls.shipping_option_update:
    post:
      summary: Shipping option update
      description: >-
        Will be called whenever the consumer selects  a shipping option. The
        order will be updated according to the response received by Checkout.
      operationId: updateShippingOption
      requestBody:
        $ref: '#/components/requestBodies/shipping_service_request'
      responses:
        '200':
          description: >-
            Shipping option looks good. The order will be updated according to
            response data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipping_service_response'
        '301':
          description: >-
            Bad shipping option. Checkout will redirect the consumer to the page
            in Location header value.
          headers: {}
        '302':
          description: >-
            Bad shipping option. Checkout will redirect the consumer to the page
            in Location header value.
          headers: {}
        '303':
          description: >-
            Bad shipping option. Checkout will redirect the consumer to the page
            in Location header value.
          headers: {}
        '307':
          description: >-
            Bad shipping option. Checkout will redirect the consumer to the page
            in Location header value.
          headers: {}
        '400':
          description: >-
            Bad address. This type of response can be used to show an error text
            message to the consumer. The response body should include one of the
            following values in the error_type field: 'address_error',
            'unsupported_shipping_address' or 'approval_failed'. An 'error_text'
            field can also be included in the response (mandatory if error_type
            is 'address_error' or 'approval_failed'). The error message will be
            shown to the consumer and he or she will be kept in the Checkout
            page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipping_service_error_response'
  /merchant_urls.validation:
    post:
      summary: Order validation
      description: >-
        Will be called before completing the purchase to validate the
        information provided by the consumer in Kustom's Checkout iframe.
      operationId: validate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/order'
      responses:
        '200':
          description: >-
            Purchase approved. The consumer will then be redirected as usual to
            the checkout confirmation page.
        '301':
          description: >-
            Purchase denied. Checkout will redirect the consumer to the page in
            Location header value.
          headers: {}
        '302':
          description: >-
            Purchase denied. Checkout will redirect the consumer to the page in
            Location header value.
          headers: {}
        '303':
          description: >-
            Purchase denied. Checkout will redirect the consumer to the page in
            Location header value.
          headers: {}
        '307':
          description: >-
            Purchase denied. Checkout will redirect the consumer to the page in
            Location header value.
          headers: {}
        '400':
          description: >-
            This type of response can be used to show an error text message to
            the consumer. The response body should include one of the following
            values in the error_type field: 'address_error',
            'unsupported_shipping_address' or 'approval_failed'. An 'error_text'
            field can also be included in the response (mandatory if error_type
            is 'address_error' or 'approval_failed'). The error message will be
            shown to the consumer and he or she will be kept in the Checkout
            page.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/shipping_service_error_response'
servers:
  - url: https://api.kustom.co
components:
  requestBodies:
    shipping_service_request:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/shipping_service_request'
  schemas:
    shipping_service_error_response:
      type: object
      required:
        - error_text
        - error_type
      properties:
        error_type:
          type: string
          example: address_error
          description: >-
            Error type. Possible values: <em>unsupported_shipping_address</em>,
            <em>address_error</em> or <em>approval_failed</em>
        error_text:
          type: string
          example: Ooops, something went wrong...
          description: >-
            Error text. Required if error_type is <em>address_error</em> or
            <em>approval_failed</em>
    DeliveryDetailsV1:
      type: object
      properties:
        carrier:
          type: string
          description: Carrier product name
        class:
          type: string
          description: Type of shipping class
        product:
          $ref: '#/components/schemas/ProductV1'
        timeslot:
          $ref: '#/components/schemas/TimeslotV1'
        pickup_location:
          $ref: '#/components/schemas/PickupLocationV1'
    PickupLocationV1:
      type: object
      properties:
        id:
          type: string
          description: Id
        name:
          type: string
          description: Name of the location
        address:
          $ref: '#/components/schemas/address'
    ProductV1:
      type: object
      properties:
        name:
          type: string
          description: Carrier product name
        identifier:
          type: string
          description: Carrier product identifier
    TimeslotV1:
      type: object
      properties:
        id:
          type: string
          description: Id
        start:
          type: string
          description: Start time
        end:
          type: string
          description: End time
    address:
      type: object
      properties:
        given_name:
          type: string
          example: John
          description: Given name.
        family_name:
          type: string
          example: Doe
          description: Family name.
        email:
          type: string
          example: john@doe.com
          description: E-mail address.
        title:
          type: string
          example: Mr
          description: >-
            Title.<p>Valid values for
            UK:</p><ul><li><em>Mr</em></li><li><em>Ms</em></li><li><em>Mrs</em></li><li><em>Miss</em></li></ul><p>Valid
            values for
            DACH:</p><ul><li><em>Herr</em></li><li><em>Frau</em></li></ul><p>Valid
            values for
            NL:</p><ul><li><em>Dhr.</em></li><li><em>Mevr.</em></li></ul>
        street_address:
          type: string
          example: Lombard St 10
          description: Street address, first line. (Street name and number)
        street_address2:
          type: string
          example: Apt 214
          description: Street address, second line. (Apartment number, suite, etc.)
        street_name:
          type: string
          example: Lombard St
          description: >-
            Street name. Only applicable in DE/AT/NL. Do not combine with
            street_address. See <b>streetNumber</b>.
        street_number:
          type: string
          example: '10'
          description: >-
            Street number. Only applicable in DE/AT/NL. Do not combine with
            street_address. See <b>streetName</b>.
        house_extension:
          type: string
          example: B
          description: House extension. Only applicable in NL
        postal_code:
          type: string
          example: '90210'
          description: Postal/post code.
        city:
          type: string
          example: Beverly Hills
          description: City.
        region:
          type: string
          example: CA
          description: State or Region.
        phone:
          type: string
          example: '333444555'
          description: Phone number.
        country:
          type: string
          example: US
          description: ISO 3166 alpha-2. Country.
        care_of:
          type: string
          example: C/O
          description: Care of.
    attachment:
      type: object
      required:
        - body
        - content_type
      properties:
        body:
          type: string
          example: >-
            {"hotel_reservation_details": [{"pnr": "VH67899","hotel_intinerary":
            [{"hotel_name": "Hotel ltd.","address": {"street_address":
            "Storgatan 3","postal_code": "113 35","city": "Stockholm","country":
            "Sweden"},"start_time": "2019-01-31T15:00:00Z","end_time":
            "2019-01-31T15:30:00Z","number_of_rooms":
            2,"ticket_delivery_method": "email","ticket_delivery_recipient":
            "jonas.larlsson@kustom.com","hotel_price": 23050,"class":
            "Business","passenger_id": [1]}],"passengers": [{"id": 1,"title":
            "mr","first_name": "Adam","last_name": "Adamson"}],"insurance":
            [{"insurance_company": "Insurance Company X","insurance_type":
            "travel","insurance_price": 0}],"affiliate_name": "TradeMaxi
            AB"}],"air_reservation_details": [{"pnr": "VH67899","intinerary":
            [{"departure": "ARN","departure_city": "Stockholm","arrival":
            "NCE","arrival_city": "Nice","carrier": "SK","segment_price":
            34000,"departure_date":
            "2019-01-30T15:00:00Z","ticket_delivery_method":
            "email","ticket_delivery_recipient":
            "jonas.larlsson@kustom.com","passenger_id": [1]}],"passengers":
            [{"id": 1,"title": "mr","first_name": "Adam","last_name":
            "Adamson"}],"insurance": [{"insurance_company": "Insurance Company
            X","insurance_type": "travel","insurance_price":
            0}],"affiliate_name": "TradeMaxi AB"}],"customer_account_info":
            [{"unique_account_identifier": "12345","account_registration_date":
            "2016-01-24T15:00:00Z","account_last_modified":
            "2017-01-24T15:00:00Z"}],"payment_history_full": [{"payment_option":
            "card","number_paid_purchases": 2,"total_amount_paid_purchases":
            1234,"date_of_last_paid_purchase":
            "2018-01-24T15:00:00Z","date_of_first_paid_purchase":
            "2018-01-24T15:00:00Z"}]}
          description: >-
            The content of the extra merchant data which should be presented as
            a string inside this property. The body should be an object
            containing any of the keys and sub objects described below
            serialised to JSON.
        content_type:
          type: string
          example: application/vnd.klarna.internal.emd-v2+json
          description: >-
            The content type of the body. It is usually represented as
            "application/vnd.klarna.internal.emd-v2+json"
    checkbox:
      type: object
      required:
        - checked
        - required
        - text
      properties:
        text:
          type: string
          example: >-
            Please add me to the newsletter list, read more here
            \[link\](http://www.google.com)
          description: >-
            Text that will be displayed to the consumer aside the checkbox.
            Links and formatting can be added using Markdown. (max 1000
            characters)
        checked:
          type: boolean
          description: >-
            Default state of the additional checkbox. It will use this value
            when loaded for the first time.
        required:
          type: boolean
          description: >-
            Whether it is required for the consumer to check the additional
            checkbox box or not in order to complete the purchase.
    checkbox-v2:
      type: object
      required:
        - checked
        - id
        - required
        - text
      properties:
        text:
          type: string
          example: >-
            Please add me to the newsletter list, read more here
            \[link\](http://www.google.com)
          description: >-
            Text that will be displayed to the consumer aside the checkbox.
            Links and formatting can be added using Markdown. (max 1000
            characters)
        checked:
          type: boolean
          description: >-
            Default state of the additional checkbox. It will use this value
            when loaded for the first time.
        required:
          type: boolean
          description: >-
            Whether it is required for the consumer to check the additional
            checkbox box or not in order to complete the purchase.
        id:
          type: string
          example: newsletter_opt_in
          description: Identifier used when presenting data back to merchant
    customer:
      type: object
      properties:
        type:
          type: string
          example: person
          description: >-
            The default supported value is 'person'. If B2B is enabled for the
            merchant, the value may be "organization".
        gender:
          type: string
          example: male
          description: Customer’s gender - ‘male’ or ‘female’.
        date_of_birth:
          type: string
          example: '1995-10-20'
          description: Customer’s date of birth. The format is ‘yyyy-mm-dd’. ISO 8601 date.
        organization_registration_id:
          type: string
          example: 556737-0431
          description: |-
            "The organization's official registration id (organization number).

            Note: Applicable only for B2B orders."
        vat_id:
          type: string
          description: Organization VAT ID. Only applies for b2b orders.
    dimensions:
      type: object
      properties:
        height:
          type: integer
          format: int64
          example: 100
          description: >-
            The product's height as used in the merchant's webshop.
            Non-negative. Measured in millimeters.
        width:
          type: integer
          format: int64
          example: 100
          description: >-
            The product's width as used in the merchant's webshop. Non-negative.
            Measured in millimeters.
        length:
          type: integer
          format: int64
          example: 100
          description: >-
            The product's length as used in the merchant's webshop.
            Non-negative. Measured in millimeters.
    discount_line:
      type: object
      required:
        - name
        - quantity
        - tax_rate
        - total_amount
        - total_tax_amount
        - unit_price
      properties:
        name:
          type: string
          example: Super deal
          description: Descriptive name of discount
          minLength: 1
          maxLength: 255
        quantity:
          type: integer
          format: int64
          example: 5
          description: Non-negative number. Quantity of the discount line item.
          minimum: 0
        unit_price:
          type: integer
          format: int64
          example: -10000
          description: >-
            Minor units. Includes tax, excludes discount. (Must be
            non-positive).


            Example: -100 Euros should be -10000.
          maximum: 0
        tax_rate:
          type: integer
          format: int64
          example: 1000
          description: >-
            Non-negative value. The percentage value is represented with two
            implicit decimals. (max 10000)


            Example: 25% should be 2500.
          maximum: 10000
        total_amount:
          type: integer
          format: int64
          example: -2500
          description: |-
            Minor units. Includes tax and discount. 

            Example: -25 euros should be -2500
            Value = (quantity x unit_price).
            (Must be non-positive)
          maximum: 0
        total_tax_amount:
          type: integer
          format: int64
          example: -123
          description: >-
            Must be within ±1 of total_amount - total_amount \* 10000 / (10000 +
            tax_rate). Should be non-positive
        reference:
          type: string
          example: 645f54bb-dbb7-6e1f-83bd-bc81a2c3a258
          description: The CRM reference to the gift-card that was entered by the user
          minLength: 0
          maxLength: 255
        merchant_data:
          type: string
          example: '{"card_number":"5551234567890"}'
          description: The gift-card number that was entered by the user
          minLength: 0
          maxLength: 1024
    gui:
      type: object
      properties:
        options:
          type: array
          description: >-
            An array of options to define the checkout behaviour. Supported
            options: minimal_confirmation.


            The gui object is an array of options to modify checkout client ui
            behaviours. 


            Examples: ["minimal_confirmation"]
          items:
            type: string
    merchant_requested:
      type: object
      properties:
        additional_checkbox:
          type: boolean
          description: >-
            Informs whether the additional_checkbox is checked or not, when
            applicable.
          readOnly: true
        additional_checkboxes:
          type: array
          description: >-
            Informs whether the additional_checkboxes is checked or not, when
            applicable.
          readOnly: true
          items:
            $ref: '#/components/schemas/merchant_requested_checkbox'
    merchant_requested_checkbox:
      type: object
      properties:
        id:
          type: string
        checked:
          type: boolean
    merchant_urls:
      type: object
      required:
        - checkout
        - confirmation
        - push
        - terms
      properties:
        terms:
          type: string
          example: https://www.example.com/terms.html
          description: >-
            URL for the terms and conditions page of the merchant. The URL will
            be displayed inside the Kustom Checkout iFrame.(max 2000 characters)

            Example: "https://merchant.com/terms"
          minLength: 0
          maxLength: 2000
        checkout:
          type: string
          example: https://www.example.com/checkout.html
          description: |-
            URL for the checkout page of the merchant. (max 2000 characters)
            Example: "https://merchant.com/checkout"
          minLength: 0
          maxLength: 2000
        confirmation:
          type: string
          example: https://www.example.com/confirmation.html
          description: >-
            URL of the merchant confirmation page. The consumer will be
            redirected back to the confirmation page if the authorization is
            successful after the customer clicks on the ‘Place Order’ button
            inside checkout. The special characters of the confirmation URL
            should be encoded, e.g. the "space" character should be written as
            "%20". Then, on top of that, the whole confirmation URL should be
            encoded. E.g. the "space" character should become "%2520". (max 2000
            characters)

            Example: "https://merchant.com/confirmation"
          minLength: 0
          maxLength: 2000
        push:
          type: string
          example: https://www.example.com/api/push
          description: >-
            URL that will be used for push notification when an order is
            completed. Should be different than checkout and confirmation URLs.
            (max 2000 characters)

            Example: "https://merchant.com/push"
          minLength: 0
          maxLength: 2000
        validation:
          type: string
          example: https://www.example.com/api/validation
          description: >-
            URL that will be requested for final merchant validation. (must be
            https, max 2000 characters)

            Example: "https://merchant.com/validation"
          minLength: 0
          maxLength: 2000
        notification:
          type: string
          example: https://www.example.com/api/pending
          description: |-
            URL for notifications on pending orders. (max 2000 characters)
            Example: "https://merchant.com/notification/{checkout.order.id}"
          minLength: 0
          maxLength: 2000
        cancellation_terms:
          type: string
          example: https://www.example.com/terms/cancellation.html
          description: >-
            URL for the cancellation terms page of the merchant. The URL will be
            displayed in the email that is sent to the customer after the order
            is captured.(max 2000 characters)

            Example: "https://merchant.com/terms/cancelation"
          minLength: 0
          maxLength: 2000
        shipping_option_update:
          type: string
          example: https://www.example.com/api/shipment
          description: |-
            URL for shipping option update. (must be https, max 2000 characters)
            Example: "https://merchant.com/shippingoptionupdate"
          minLength: 0
          maxLength: 2000
        address_update:
          type: string
          example: https://www.example.com/api/address
          description: >-
            URL for shipping, tax and purchase currency updates. Will be called
            on address changes. (must be https, max 2000 characters)

            Example: "https://merchant.com/addressupdate"
          minLength: 0
          maxLength: 2000
        country_change:
          type: string
          example: https://www.example.com/api/country
          description: >-
            URL for shipping, tax and purchase currency updates. Will be called
            on billing or shipping country changes. (must be https, max 2000
            characters)

            Example: "https://merchant.com/countrychange"
          minLength: 0
          maxLength: 2000
    options:
      type: object
      properties:
        require_validate_callback_success:
          type: boolean
          description: >-
            If true, validate callback must get a positive response to not stop
            purchase. Default: false.
        acquiring_channel:
          type: string
          description: >-
            Acquiring channel for the order. The possible values are:

            <ul><li><em>ECOMMERCE for "E-commerce"</em></li><li><em>IN_STORE for
            "Purchase in boutique"</em></li><li><em>Default :
            ECOMMERCE</em></li></ul>
          pattern: ECOMMERCE|MOTO|IN_STORE|TELESALES
        vat_removed:
          type: boolean
          description: If true, VAT is not displayed in Checkout's Order Summary page.
        allow_separate_shipping_address:
          type: boolean
          description: >-
            If true, the consumer can enter different billing and shipping
            addresses. Default: false, except for purchase_country DE where
            default is: true
        color_button:
          type: string
          example: '#FF9900'
          description: >-
            Color for the buttons within the iFrame. Value should be a CSS hex
            color, e.g. "#FF9900"
          pattern: ^#[A-Fa-f0-9]{6}$
        color_button_text:
          type: string
          example: '#FF9900'
          description: >-
            Color for the text inside the buttons within the iFrame. Value
            should be a CSS hex color, e.g. "#FF9900"
          pattern: ^#[A-Fa-f0-9]{6}$
        color_checkbox:
          type: string
          example: '#FF9900'
          description: >-
            Color for the checkboxes within the iFrame. Value should be a CSS
            hex color, e.g. "#FF9900"
          pattern: ^#[A-Fa-f0-9]{6}$
        color_checkbox_checkmark:
          type: string
          example: '#FF9900'
          description: >-
            Color for the checkboxes checkmark within the iFrame. Value should
            be a CSS hex color, e.g. "#FF9900"
          pattern: ^#[A-Fa-f0-9]{6}$
        color_header:
          type: string
          example: '#FF9900'
          description: >-
            Color for the headers within the iFrame. Value should be a CSS hex
            color, e.g. "#FF9900"
          pattern: ^#[A-Fa-f0-9]{6}$
        color_link:
          type: string
          example: '#FF9900'
          description: >-
            Color for the hyperlinks within the iFrame. Value should be a CSS
            hex color, e.g. "#FF9900"
          pattern: ^#[A-Fa-f0-9]{6}$
        date_of_birth_mandatory:
          type: boolean
          description: 'If true, the consumer cannot skip date of birth. Default: false'
        shipping_details:
          type: string
          example: Delivered within 1-3 working days
          description: >-
            A message that will be presented on the confirmation page under the
            headline "Delivery" (max 255 characters).
        title_mandatory:
          type: boolean
          description: >-
            If specified to false, title becomes optional. Only available for
            orders for country GB.
        additional_checkbox:
          $ref: '#/components/schemas/checkbox'
        national_identification_number_mandatory:
          type: boolean
          description: >-
            If true, the user cannot skip national identification number in SE,
            NO, FI and DK. Default: false. In order to read the national
            identification number in the validation callback, please contact
            Kustom’s merchant support.
        additional_merchant_terms:
          type: string
          description: >-
            Additional merchant defined field. e.g. Extra terms and conditions
            to show.


            Example: "ADDITIONAL MERCHANT TERMS! \[terms
            link\](https://merchant.com/extra_terms)"
        phone_mandatory:
          type: boolean
          description: >-
            If false, the consumer can skip the phone. Only available for orders
            in DACH countries.
        radius_border:
          type: string
          example: '5'
          description: Radius for the border of elements within the iFrame.
        allowed_customer_types:
          type: array
          description: >-
            A list of allowed customer types. Supported types: <b>person</b> &
            <b>organization</b>.

            Example: ["person","organization"]
          items:
            type: string
          maxItems: 2
          minItems: 1
        show_subtotal_detail:
          type: boolean
          description: >-
            If true, the Order Detail subtotals view is expanded when the Kustom
            Checkout iFrame is loaded. Default: false
        additional_checkboxes:
          type: array
          items:
            $ref: '#/components/schemas/checkbox-v2'
        verify_national_identification_number:
          type: boolean
          description: >-
            Enable verification of National Identification Numbers only in
            Sweden and Norway. This option also make the national identification
            number mandatory. (Not applicable for countries outside of Sweden
            and Norway)
        auto_capture:
          type: boolean
          description: Allow merchant to trigger auto capturing.
        require_client_validation:
          type: boolean
          description: If true, a client side validation is needed to complete the purchase
        enable_discount_module:
          type: boolean
          description: Enables the inline discount module
        show_vat_registration_number_field:
          type: boolean
          description: >-
            If true, a optional VAT registration number field will be shown in
            the address form. Only applies for b2b orders.
    order:
      type: object
      required:
        - locale
        - order_amount
        - order_lines
        - order_tax_amount
        - purchase_country
        - purchase_currency
      properties:
        order_id:
          type: string
          example: f3392f8b-6116-4073-ab96-e330819e2c07
          description: >-
            Unique order ID that will be used for the entire lifecycle of the
            order. (max 255 characters)
          readOnly: true
        name:
          type: string
          example: Women's Fashion
          description: The merchant name (max 255 characters).
          readOnly: true
        purchase_country:
          type: string
          example: US
          description: >-
            The purchase country of the merchant's store. The format to be used
            is ISO 3166 alpha-2. Eg: GB, SE, DE, US, etc. 


            Note: purchase country and currency need to match the defined
            merchant configuration. For global configuration see more details
            [here](/contents/checkout/use-cases/selling-to-multiple-countries/)
          pattern: ^[A-Za-z]{2,2}$
        purchase_currency:
          type: string
          example: USD
          description: >-
            The purchase currency of the merchant's store. The format to be used
            is ISO 4217. Eg: USD, EUR, SEK, GBP, etc.


            Note: purchase country and currency need to match the defined
            merchant configuration. For global configuration see more details
            [here](/contents/checkout/use-cases/selling-to-multiple-countries/)
          pattern: ^[A-Za-z]{3,3}$
        locale:
          type: string
          example: en-US
          description: >-
            Used to define the language and region of the customer. RFC 1766
            customer's locale.
          pattern: ^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$
        status:
          type: string
          example: CHECKOUT_INCOMPLETE
          description: >-
            The current status of the order. The status will be ‘incomplete’
            until the customer has been successfully authorized.
        billing_address:
          $ref: '#/components/schemas/address'
        shipping_address:
          $ref: '#/components/schemas/address'
        order_amount:
          type: integer
          format: int64
          example: 50000
          description: >-
            Total amount of the order including tax and any available discounts.
            The value should be in non-negative minor units.


            Example: 25 Euros should be 2500.
          minimum: 0
        order_tax_amount:
          type: integer
          format: int64
          example: 4545
          description: >-
            Total tax amount of the order. The value should be in non-negative
            minor units.


            Example: 25 Euros should be 2500.
          minimum: 0
        order_lines:
          type: array
          description: >-
            An array containing list of line items that are part of this order.
            Maximum of 1000 line items could be processed in a single order.
          items:
            $ref: '#/components/schemas/order_line'
          maxItems: 1000
          minItems: 0
        customer:
          $ref: '#/components/schemas/customer'
        merchant_urls:
          $ref: '#/components/schemas/merchant_urls'
        html_snippet:
          type: string
          example: >-
            <div id='klarna-checkout-container'><script>alert('Initializing
            Kustom Checkout');</script></div>
          description: The HTML snippet that is used to render the checkout in an iframe.
          readOnly: true
        merchant_reference1:
          type: string
          example: 45aa52f387871e3a210645d4
          description: >-
            Used for storing merchant's internal order number or other
            reference. If set, will be shown on the confirmation page as "order
            number" . The value is also available in the settlement files. (max
            255 characters).

            Example: "45aa52f387871e3a210645d4"
          minLength: 0
          maxLength: 255
        merchant_reference2:
          type: string
          example: 45aa52f387871e3a210645d4
          description: >-
            Used for storing merchant's internal order number or other
            reference. The value is available in the settlement files. (max 255
            characters).

            Example: "45aa52f387871e3a210645d4"
          minLength: 0
          maxLength: 255
        started_at:
          type: string
          format: date-time
          description: >-
            ISO 8601 datetime. The date and time when the order has been
            created. The format will be as follows:

            "yyyy-mm-ddThh:mm:ssZ"
          readOnly: true
        completed_at:
          type: string
          format: date-time
          description: >-
            ISO 8601 datetime. The date and time when the order has been
            completed. The format will be as follows:

            "yyyy-mm-ddThh:mm:ssZ"
          readOnly: true
        last_modified_at:
          type: string
          format: date-time
          description: >-
            ISO 8601 datetime. The date and time when the order was last
            modified. The format will be as follows:

            "yyyy-mm-ddThh:mm:ssZ"
          readOnly: true
        options:
          $ref: '#/components/schemas/options'
        attachment:
          $ref: '#/components/schemas/attachment'
        external_payment_methods:
          type: array
          description: >-
            List of external payment methods that will be displayed as part of
            payment methods in the checkout.
          items:
            $ref: '#/components/schemas/payment_provider'
        external_checkouts:
          type: array
          description: >-
            List of external checkouts that will be displayed as part of payment
            methods in the checkout.

            The image_url is required, and the image size has to be 276x48px
          items:
            $ref: '#/components/schemas/payment_provider'
        shipping_countries:
          type: array
          description: >-
            List of allowed shipping countries for this order in ISO-3166
            alpha-2 format.


            If specified, the customer will be able to change the shipping
            country in the checkout and you will be notified through
            ‘address_update’ callback or the ‘shipping_address_change’
            javascript event. 


            If not specified then the default value will be the purchase
            country.


            Example: look at billing_countries example.
          items:
            type: string
        shipping_options:
          type: array
          description: A list of shipping options available for this order.
          items:
            $ref: '#/components/schemas/shipping_option'
        merchant_data:
          type: string
          example: >-
            {"marketplace_seller_info":[{"product_category":"Women's
            Fashion","product_name":"Women Sweatshirt"}]}
          description: >-
            Pass through field to send any information about the order to be
            used later for reference while retrieving the order details (max
            6000 characters).
          minLength: 0
          maxLength: 6000
        gui:
          $ref: '#/components/schemas/gui'
        merchant_requested:
          $ref: '#/components/schemas/merchant_requested'
        selected_shipping_option:
          $ref: '#/components/schemas/shipping_option'
        recurring:
          type: boolean
          description: >-
            Indicates whether this purchase will create a token that can be used
            by the merchant to create recurring purchases. This must be enabled
            for the merchant to use. Default: false


            Depending on specified country, recurring could be used for the
            following payment methods: Pay Later, Direct Debit, Card.
        recurring_token:
          type: string
          description: Token to be used when creating recurring orders.
          readOnly: true
        recurring_description:
          type: string
          description: Description to be added to the recurring order.
          readOnly: true
          minLength: 0
          maxLength: 255
        billing_countries:
          type: array
          description: >-
            List of allowed billing countries for this order.

            If specified, the customer will be able to change the billing
            country in the checkout and you will be notified through
            ‘country_change’ callback or the ‘billing_address_change’ javascript
            event.

            If not specified but shipping_countries is specified, will use same
            values as shipping_countries.

            If not specified and shipping_countries is not specified, then the
            default value will be the purchase country.


            Example: ["AD", "AE", "AG", "AI", "AL", "AM", "AQ", "AR", "AS",
            "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG",
            "BH", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BW",
            "BY", "BZ", "CA", "CF", "CH", "CI", "CK", "CL", "CM", "CN", "CO",
            "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM",
            "DO", "DZ", "EC", "EE", "EG", "ER", "ES", "ET", "FI", "FJ", "FK",
            "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI",
            "GL", "GM", "GN", "GP", "GR", "GS", "GT", "GU", "GY", "HK", "HN",
            "HR", "HU", "ID", "IE", "IL", "IM", "IN", "IS", "IT", "JE", "JM",
            "JO", "JP", "KE", "KG", "KI", "KM", "KN", "KR", "KW", "KY", "KZ",
            "LA", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV",
            "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "MK", "ML", "MM",
            "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY",
            "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR",
            "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM",
            "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW",
            "SA", "SB", "SC", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM",
            "SN", "SR", "ST", "SV", "SX", "SZ", "TC", "TF", "TG", "TH", "TJ",
            "TK", "TL", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM",
            "US", "UY", "UZ", "VA", "VC", "VG", "VI", "VN", "VU", "WF", "WS",
            "XK", "YT", "ZA", "ZM", "ZW"]"
          items:
            type: string
        tags:
          type: array
          description: |-
            Extra information added to the order.

            Example: ["dangerous_goods", "bulky"]
          items:
            type: string
        discount_lines:
          type: array
          description: List of discounts applied to this order via the KCO discount-service
          items:
            $ref: '#/components/schemas/discount_line'
    order_line:
      type: object
      required:
        - name
        - quantity
        - tax_rate
        - total_amount
        - total_tax_amount
        - unit_price
      properties:
        type:
          type: string
          example: physical
          description: >-
            Type of the order line item. The possible values
            are:<ul><li><em>physical (physical
            good)</em></li><li><em>discount</em></li><li><em>shipping_fee</em></li><li><em>sales_tax
            (depends on the country/city, usually called
            VAT)</em></li><li><em>digital (digital
            good)</em></li><li><em>gift_card</em></li><li><em>store_credit
            (credit from the merchant)</em></li><li><em>surcharge (extra
            charge)</em></li></ul>
        reference:
          type: string
          example: 19-402-USA
          description: Article number, SKU or similar. (max 255 characters)
          minLength: 0
          maxLength: 255
        name:
          type: string
          example: Red T-Shirt
          description: Descriptive name of the order line item (max 255 characters)
          minLength: 1
          maxLength: 255
        quantity:
          type: integer
          format: int64
          example: 5
          description: Non-negative number. Quantity of the order line item.
          minimum: 0
        subscription:
          $ref: '#/components/schemas/subscription'
        quantity_unit:
          type: string
          example: pcs
          description: >-
            Unit used to describe the quantity, e.g. kg, pcs... If defined has
            to be 1-8 characters
        unit_price:
          type: integer
          format: int64
          example: 10000
          description: >-
            Minor units. Includes tax, excludes discount. (max value:
            100000000).


            Example: 100 Euros should be 10000.
          maximum: 100000000
        tax_rate:
          type: integer
          format: int64
          example: 1000
          description: >-
            Non-negative value. The percentage value is represented with two
            implicit decimals. (max 10000)


            Example: 25% should be 2500.
          maximum: 10000
        total_amount:
          type: integer
          format: int64
          example: 50000
          description: |-
            Minor units. Includes tax and discount. 

            Example: 25 euros should be 2500
            Value = (quantity x unit_price) - total_discount_amount.
            (max value: 100000000)
          maximum: 100000000
        total_discount_amount:
          type: integer
          format: int64
          example: 0
          description: |-
            Non-negative minor units. Includes tax.

            Example: 25 euros should be 2500
          minimum: 0
        total_tax_amount:
          type: integer
          format: int64
          example: 4545
          description: >-
            Must be within ±1 of total_amount - total_amount \* 10000 / (10000 +
            tax_rate). Negative when type is discount.
        merchant_data:
          type: string
          example: >-
            {"marketplace_seller_info":[{"product_category":"Women's
            Fashion","product_name":"Women Sweatshirt"}]}
          description: >-
            Property used to store additional metadata per item that will be
            returned whenever an order is read from Kustom. Pass through field.
            (max 1024 characters).
          minLength: 0
          maxLength: 1024
        product_url:
          type: string
          example: https://www.example.com/products/f2a8d7e34
          description: >-
            URL to the product page that can be later embedded in communications
            between Kustom and the customer. (max 1024 characters)
          minLength: 0
          maxLength: 1024
        image_url:
          type: string
          example: https://www.exampleobjects.com/product-image-1200x1200.jpg
          description: >-
            URL to an image that can be later embedded in communications between
            Kustom and the customer. (max 1024 characters)


            Improves post-purchase customer experiences.
          minLength: 0
          maxLength: 1024
        product_identifiers:
          $ref: '#/components/schemas/product_identifiers'
        shipping_attributes:
          $ref: '#/components/schemas/shipping_attributes'
    payment_provider:
      type: object
      required:
        - name
        - redirect_url
      properties:
        name:
          type: string
          example: PayhereUs
          description: The name of the payment provider. (max 255 characters)
          minLength: 0
          maxLength: 255
        fee:
          type: integer
          format: int64
          description: Minor units. Includes tax.
        description:
          type: string
          example: an American company operating a worldwide online payments system
          description: >-
            Short description of the payment method. This is displayed below the
            selected payment method. (max 500 characters)
          minLength: 0
          maxLength: 500
        countries:
          type: array
          description: >-
            If specified, limits the method to the listed countries (alpha 2
            codes).
          items:
            type: string
        label:
          type: string
          example: continue
          description: >-
            Controls label of buy
            button<ul><li>continue</li><li>complete</li></ul>
        redirect_url:
          type: string
          example: https://www.example.com/us/start
          description: URL to redirect to. (must be https, min 7, max 2000 characters)
          minLength: 7
          maxLength: 2000
        image_url:
          type: string
          example: https://www.exampleobjects.com/product-image-1200x1200.jpg
          description: URL to an image to display. (must be https, max 2000 characters)
          minLength: 0
          maxLength: 2000
    product_identifiers:
      type: object
      properties:
        brand:
          type: string
          example: Intel
          description: >-
            The product's brand name as generally recognized by consumers. If no
            brand is available for a product, do not supply any value.
          minLength: 0
          maxLength: 70
        color:
          type: string
          example: Blue
          description: Color to be shown to the end customer (max 64 characters).
          minLength: 0
          maxLength: 64
        category_path:
          type: string
          example: Electronics Store > Computers & Tablets > Desktops
          description: >-
            The product's category path as used in the merchant's webshop.
            Include the full and most detailed category and separate the
            segments with ' > '. (max 750 characters)


            Example: "Electronics Store > Computers & Tablets > Desktops"
          minLength: 0
          maxLength: 750
        global_trade_item_number:
          type: string
          example: '735858293167'
          description: >-
            The product's Global Trade Item Number (GTIN). Common types of GTIN
            are EAN, ISBN or UPC. Exclude dashes and spaces, where possible
          minLength: 0
          maxLength: 50
        manufacturer_part_number:
          type: string
          example: BOXNUC5CPYH
          description: >-
            The product's Manufacturer Part Number (MPN), which - together with
            the brand - uniquely identifies a product. Only submit MPNs assigned
            by a manufacturer and use the most specific MPN possible
          minLength: 0
          maxLength: 70
        size:
          type: string
          example: Medium
          description: Size to be shown to the end customer (max 64 characters).
          minLength: 0
          maxLength: 64
    selected_addon:
      type: object
      properties:
        type:
          type: string
        price:
          type: integer
          format: int64
        external_id:
          type: string
        user_input:
          type: string
    shipping_attributes:
      type: object
      properties:
        weight:
          type: integer
          format: int64
          example: 1000
          description: >-
            The product's weight as used in the merchant's webshop.
            Non-negative. Measured in grams.
        dimensions:
          $ref: '#/components/schemas/dimensions'
        tags:
          type: array
          description: The product's extra features, example ["dangerous_goods", "bulky"]
          items:
            type: string
    shipping_option:
      type: object
      required:
        - id
        - name
        - price
        - tax_amount
        - tax_rate
      properties:
        id:
          type: string
          example: express_priority
          description: id
        name:
          type: string
          example: EXPRESS 1-2 Days
          description: Name.
          minLength: 1
          maxLength: 255
        description:
          type: string
          example: Delivery by 4:30 pm
          description: Description.
        promo:
          type: string
          example: Christmas Promotion
          description: Promotion name. To be used if this shipping option is promotional.
        price:
          type: integer
          format: int64
          description: Price including tax.
        preselected:
          type: boolean
          description: >-
            If true, this option will be preselected when checkout loads.
            Default: false
        tax_amount:
          type: integer
          format: int64
          description: Tax amount.
        tax_rate:
          type: integer
          format: int64
          description: Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
        shipping_method:
          type: string
          example: PickUpStore
          description: >-
            Shipping method. Possible
            values:<ul><li>PickUpStore</li><li>Home</li><li>BoxReg</li><li>BoxUnreg</li><li>PickUpPoint</li><li>Own</li><li>Postal</li><li>DHLPackstation</li><li>Digital</li></ul>
            If DHLPackstation is selected the correct form will be displayed.
        delivery_details:
          $ref: '#/components/schemas/DeliveryDetailsV1'
        tms_reference:
          type: string
          example: a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6
          description: >-
            TMS reference. Required to map completed orders to shipments
            reserved in TMS.
        selected_addons:
          type: array
          items:
            $ref: '#/components/schemas/selected_addon'
    subscription:
      type: object
      required:
        - interval
        - interval_count
      properties:
        name:
          type: string
          description: |-
            The name of the subscription product.

            Example: "Premium Account"
        interval:
          type: string
          description: |-
            The cadence unit for this.

            Example: "DAY"
          enum:
            - DAY
            - WEEK
            - MONTH
            - YEAR
        interval_count:
          type: integer
          format: int32
          description: |-
            The number of intervals.

            Example: 30
          minimum: 1
    shipping_service_response:
      type: object
      required:
        - order_amount
        - order_lines
        - order_tax_amount
        - purchase_currency
      properties:
        order_amount:
          type: integer
          format: int64
          description: >-
            Non-negative, minor units. Total total amount of the order,
            including tax and any discounts.
          minimum: 0
        order_tax_amount:
          type: integer
          format: int64
          description: Non-negative, minor units. The total tax amount of the order.
          minimum: 0
        merchant_data:
          type: string
          example: >-
            {"marketplace_seller_info":[{"product_category":"Women's
            Fashion","product_name":"Women Sweatshirt"}]}
          description: Pass through field (max 1024 characters).
          minLength: 0
          maxLength: 1024
        order_lines:
          type: array
          description: The applicable order lines (max 1000)
          items:
            $ref: '#/components/schemas/order_line'
          maxItems: 1000
          minItems: 0
        shipping_options:
          type: array
          description: A list of shipping options available for this order.
          items:
            $ref: '#/components/schemas/shipping_option'
        attachment:
          $ref: '#/components/schemas/attachment'
        purchase_currency:
          type: string
          example: USD
          description: ISO 4217 purchase currency.
          pattern: ^[A-Za-z]{3,3}$
        locale:
          type: string
          example: en-US
          description: RFC 1766 customer's locale.
          pattern: ^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$
        external_payment_methods:
          type: array
          description: >-
            List of external payment methods that will be displayed as part of
            payment methods in the checkout.
          items:
            $ref: '#/components/schemas/payment_provider'
        tags:
          type: array
          description: |-
            Extra information added to the order.

            Example: ["dangerous_goods", "bulky"]
          items:
            type: string
    AddressV1:
      type: object
      properties:
        given_name:
          type: string
          example: John
          description: Given name.
        family_name:
          type: string
          example: Doe
          description: Family name.
        email:
          type: string
          example: john@doe.com
          description: E-mail address.
        title:
          type: string
          example: Mr
          description: >-
            Title.<p>Valid values for
            UK:</p><ul><li><em>Mr</em></li><li><em>Ms</em></li><li><em>Mrs</em></li><li><em>Miss</em></li></ul><p>Valid
            values for
            DACH:</p><ul><li><em>Herr</em></li><li><em>Frau</em></li></ul><p>Valid
            values for
            NL:</p><ul><li><em>Dhr.</em></li><li><em>Mevr.</em></li></ul>
        street_address:
          type: string
          example: Lombard St 10
          description: Street address, first line. (Street name and number)
        street_address2:
          type: string
          example: Apt 214
          description: Street address, second line. (Apartment number, suite, etc.)
        street_name:
          type: string
          example: Lombard St
          description: >-
            Street name. Only applicable in DE/AT/NL. Do not combine with
            street_address. See <b>streetNumber</b>.
        street_number:
          type: string
          example: '10'
          description: >-
            Street number. Only applicable in DE/AT/NL. Do not combine with
            street_address. See <b>streetName</b>.
        house_extension:
          type: string
          example: B
          description: House extension. Only applicable in NL
        postal_code:
          type: string
          example: '90210'
          description: Postal/post code.
        city:
          type: string
          example: Beverly Hills
          description: City.
        region:
          type: string
          example: CA
          description: State or Region.
        phone:
          type: string
          example: '333444555'
          description: Phone number.
        country:
          type: string
          example: US
          description: ISO 3166 alpha-2. Country.
        care_of:
          type: string
          example: C/O
          description: Care of.
    shipping_service_request:
      type: object
      required:
        - order_amount
        - order_lines
        - order_tax_amount
        - purchase_currency
      properties:
        order_amount:
          type: integer
          format: int64
          description: >-
            Non-negative, minor units. Total total amount of the order,
            including tax and any discounts.
          minimum: 0
        order_tax_amount:
          type: integer
          format: int64
          description: Non-negative, minor units. The total tax amount of the order.
          minimum: 0
        order_lines:
          type: array
          description: The applicable order lines (max 1000)
          items:
            $ref: '#/components/schemas/order_line'
          maxItems: 1000
          minItems: 0
        billing_address:
          $ref: '#/components/schemas/AddressV1'
        shipping_address:
          $ref: '#/components/schemas/AddressV1'
        selected_shipping_option:
          $ref: '#/components/schemas/shipping_option'
        purchase_currency:
          type: string
          example: USD
          description: ISO 4217 purchase currency.
          pattern: ^[A-Za-z]{3,3}$
        merchant_data:
          type: string
          description: Pass through field (max 6000 characters).
          readOnly: true
        merchant_reference1:
          type: string
          description: >-
            Used for storing merchant's internal order number or other
            reference. If set, will be shown on the confirmation page as "order
            number" (max 255 characters).
          readOnly: true
        merchant_reference2:
          type: string
          description: >-
            Used for storing merchant's internal order number or other reference
            (max 255 characters).
          readOnly: true
        customer:
          $ref: '#/components/schemas/customer'
        locale:
          type: string
          example: en-US
          description: RFC 1766 customer's locale.
          readOnly: true
        tags:
          type: array
          description: The product's extra features, example ["dangerous_goods", "bulky"]
          items:
            type: string
