openapi: 3.0.0
info:
  title: Order Management API
  version: 1.0.0
servers:
  - url: https://api.kustom.co/
    description: Default Server URL
paths:
  /ordermanagement/v1/orders/{order_id}/shipping-info:
    post:
      tags:
        - Orders
      summary: Add shipping information
      description: >-
        Add shipping info to an order. Read more on [Adding shipping
        info](https://docs.kustom.co/contents/order-management/manage-orders-with-the-api/view-and-change-orders#update-shipping-address)
      operationId: appendOrderShippingInfo
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: Klarna-Idempotency-Key
          in: header
          description: >-
            This header will guarantee the idempotency of the operation. The key
            should be unique and is recommended to be a UUID version 4. Retries
            of requests are safe to be applied in case of errors such as network
            errors, socket errors and timeouts. Input values of the operation
            are disregarded when evaluating the idempotency of the operation,
            only the key matters.
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateShippingInfoDto'
        required: true
      responses:
        '204':
          description: Shipping information was appended.
        '404':
          description: Order not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSuchOrderErrorMessageDto'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/release-remaining-authorization:
    post:
      tags:
        - Orders
      summary: Release an authorization
      description: >-
        Release remaining authorization. Read more on [Releasing remaining
        authorization](https://docs.kustom.co/contents/api/order-management/orders/releaseremainingauthorization)
      operationId: releaseRemainingAuthorization
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: Klarna-Idempotency-Key
          in: header
          description: >-
            This header will guarantee the idempotency of the operation. The key
            should be unique and is recommended to be a UUID version 4. Retries
            of requests are safe to be applied in case of errors such as network
            errors, socket errors and timeouts. Input values of the operation
            are disregarded when evaluating the idempotency of the operation,
            only the key matters.
          required: false
          schema:
            type: string
      responses:
        '204':
          description: Remaining authorization was released.
          content:
            application/json:
              schema:
                type: string
        '403':
          description: Can not release when order is cancelled or has no captures.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotAllowedErrorMessageDto'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/refunds:
    post:
      tags:
        - Refunds
      summary: Refund an order
      description: >-
        Create a refund. Read more on
        [Refunds](https://docs.kustom.co/contents/order-management/manage-orders-with-the-api/refund-and-extend-orders)
      operationId: refundOrder
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: Klarna-Idempotency-Key
          in: header
          description: >-
            This header will guarantee the idempotency of the operation. The key
            should be unique and is recommended to be a UUID version 4. Retries
            of requests are safe to be applied in case of errors such as network
            errors, socket errors and timeouts. Input values of the operation
            are disregarded when evaluating the idempotency of the operation,
            only the key matters.
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundObjectDto'
        required: true
      responses:
        '201':
          description: Refund created
          content:
            application/json:
              schema:
                type: string
        '403':
          description: Refund not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundNotAllowedErrorMessageDto'
        '404':
          description: Order not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorMessageDto'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/extend-authorization-time:
    post:
      tags:
        - Orders
      summary: Extend the authorization time
      description: >-
        Extend authorization time. Read more on [Extending order authorization
        time](https://docs.kustom.co/contents/order-management/manage-orders-with-the-api/extend-authorization)
      operationId: extendAuthorizationTime
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: Klarna-Idempotency-Key
          in: header
          description: >-
            This header will guarantee the idempotency of the operation. The key
            should be unique and is recommended to be a UUID version 4. Retries
            of requests are safe to be applied in case of errors such as network
            errors, socket errors and timeouts. Input values of the operation
            are disregarded when evaluating the idempotency of the operation,
            only the key matters.
          required: false
          schema:
            type: string
      responses:
        '204':
          description: Authorization time was extended.
        '403':
          description: >-
            Extension of authorization time not allowed. The order being expired
            or cancelled are among the possible causes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotAllowedErrorMessageDto'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/captures:
    get:
      tags:
        - Captures
      summary: List all order captures
      description: List all order captures
      operationId: getCaptures
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Captures found.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CaptureDto'
        '404':
          description: Order not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSuchOrderErrorMessageDto'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
    post:
      tags:
        - Captures
      summary: Capture an order
      description: >-
        Create capture. Read more on [Capturing an
        order](https://docs.kustom.co/contents/order-management/manage-orders-with-the-api/capture-and-track-orders)
      operationId: captureOrder
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: Klarna-Idempotency-Key
          in: header
          description: >-
            This header will guarantee the idempotency of the operation. The key
            should be unique and is recommended to be a UUID version 4. Retries
            of requests are safe to be applied in case of errors such as network
            errors, socket errors and timeouts. Input values of the operation
            are disregarded when evaluating the idempotency of the operation,
            only the key matters.
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptureObjectDto'
        required: true
      responses:
        '201':
          description: Capture created
        '403':
          description: Capture not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptureNotAllowedErrorMessageDto'
        '404':
          description: Order not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSuchOrderErrorMessageDto'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/captures/{capture_id}/shipping-info:
    post:
      tags:
        - Captures
      summary: Add shipping information
      description: >-
        Add shipping info to a capture. Read more on [Adding shipping
        info](https://docs.kustom.co/contents/order-management/manage-orders-with-the-api/view-and-change-orders#add-shipping-information)
      operationId: appendShippingInfo
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: capture_id
          in: path
          description: Capture id
          required: true
          schema:
            type: string
        - name: Klarna-Idempotency-Key
          in: header
          description: >-
            This header will guarantee the idempotency of the operation. The key
            should be unique and is recommended to be a UUID version 4. Retries
            of requests are safe to be applied in case of errors such as network
            errors, socket errors and timeouts. Input values of the operation
            are disregarded when evaluating the idempotency of the operation,
            only the key matters.
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateShippingInfoDto'
        required: true
      responses:
        '204':
          description: Shipping information was appended.
        '403':
          description: Order has no captures.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotAllowedErrorMessageDto'
        '404':
          description: Order or capture not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSuchOrderErrorMessageDto'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/cancel:
    post:
      tags:
        - Orders
      summary: Cancel an order
      description: >-
        Cancel order. Read more on [Cancelling an
        order](https://docs.kustom.co/contents/order-management/manage-orders-with-the-api/view-and-change-orders#cancel-order)
      operationId: cancelOrder
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: Klarna-Idempotency-Key
          in: header
          description: >-
            This header will guarantee the idempotency of the operation. The key
            should be unique and is recommended to be a UUID version 4. Retries
            of requests are safe to be applied in case of errors such as network
            errors, socket errors and timeouts. Input values of the operation
            are disregarded when evaluating the idempotency of the operation,
            only the key matters.
          required: false
          schema:
            type: string
      responses:
        '204':
          description: Order was cancelled.
        '403':
          description: Cancel not allowed (e.g. order has captures or is closed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelNotAllowedErrorMessageDto'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/acknowledge:
    post:
      tags:
        - Orders
      summary: Acknowledge a Kustom checkout order
      description: >-
        Acknowledge order. Read more on [Acknowledging
        orders](https://docs.kustom.co/contents/order-management/manage-orders-with-the-api/view-and-change-orders#acknowledge-order)
      operationId: acknowledgeOrder
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: Klarna-Idempotency-Key
          in: header
          description: >-
            This header will guarantee the idempotency of the operation. The key
            should be unique and is recommended to be a UUID version 4. Retries
            of requests are safe to be applied in case of errors such as network
            errors, socket errors and timeouts. Input values of the operation
            are disregarded when evaluating the idempotency of the operation,
            only the key matters.
          required: false
          schema:
            type: string
      responses:
        '204':
          description: Order was acknowledged.
        '403':
          description: Update not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotAllowedErrorMessageDto'
        '404':
          description: Order not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSuchOrderErrorMessageDto'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/merchant-references:
    patch:
      tags:
        - Orders
      summary: Update merchant references
      description: >-
        Update merchant references. Read more on [Updating merchant
        references](https://docs.kustom.co/contents/order-management/manage-orders-with-the-api/view-and-change-orders#update-merchant-references-1)
      operationId: updateMerchantReferences
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: Klarna-Idempotency-Key
          in: header
          description: >-
            This header will guarantee the idempotency of the operation. The key
            should be unique and is recommended to be a UUID version 4. Retries
            of requests are safe to be applied in case of errors such as network
            errors, socket errors and timeouts. Input values of the operation
            are disregarded when evaluating the idempotency of the operation,
            only the key matters.
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMerchantReferencesDto'
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/UpdateMerchantReferencesDto'
        required: true
      responses:
        '204':
          description: Order merchant references were updated.
        '403':
          description: Can not update a cancelled order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotAllowedErrorMessageDto'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/customer-details:
    patch:
      tags:
        - Orders
      summary: Update customer addresses
      description: >-
        Update shipping address. Read more on [Updating customer
        addresses](https://docs.kustom.co/contents/order-management/manage-orders-with-the-api/view-and-change-orders#update-shipping-address)
      operationId: updateConsumerDetails
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: Klarna-Idempotency-Key
          in: header
          description: >-
            This header will guarantee the idempotency of the operation. The key
            should be unique and is recommended to be a UUID version 4. Retries
            of requests are safe to be applied in case of errors such as network
            errors, socket errors and timeouts. Input values of the operation
            are disregarded when evaluating the idempotency of the operation,
            only the key matters.
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConsumerDto'
        required: true
      responses:
        '204':
          description: Order consumer details were updated.
          content:
            application/json:
              schema:
                type: string
        '403':
          description: >-
            Update customer details not allowed. Decision is based on order
            state and outcome of risk assessment. Billing address cannot be
            updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotAllowedErrorMessageDto'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/authorization:
    patch:
      tags:
        - Orders
      summary: Update the order amount and order lines
      description: >-
        Set new order amount and order lines. Read more on [Updating
        orders](https://docs.kustom.co/contents/api/order-management/orders/updateauthorization)
      operationId: updateAuthorization
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: Klarna-Idempotency-Key
          in: header
          description: >-
            This header will guarantee the idempotency of the operation. The key
            should be unique and is recommended to be a UUID version 4. Retries
            of requests are safe to be applied in case of errors such as network
            errors, socket errors and timeouts. Input values of the operation
            are disregarded when evaluating the idempotency of the operation,
            only the key matters.
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAuthorizationDto'
        required: true
      responses:
        '204':
          description: Authorization was updated.
          content:
            application/json:
              schema:
                type: string
        '403':
          description: >-
            Update authorization not allowed. Decision is based on order state
            and outcome of risk assessment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotAllowedErrorMessageDto'
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}:
    get:
      tags:
        - Orders
      summary: Get order details
      description: >-
        An order that has the given order id. Read more on [Retrieving order
        details](https://docs.kustom.co/contents/order-management/manage-orders-with-the-api/view-and-change-orders#check-the-details-of-an-order)
      operationId: getOrder
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: Klarna-Integrator
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Order found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantOrderDto'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSuchOrderErrorMessageDto'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/refunds/{refund_id}:
    get:
      tags:
        - Refunds
      summary: Get refund details
      description: 'Get refund. '
      operationId: getRefund
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: refund_id
          in: path
          description: Refund id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Refund found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundDto'
        '404':
          description: Order or refund not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorMessageDto'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
  /ordermanagement/v1/orders/{order_id}/captures/{capture_id}:
    get:
      tags:
        - Captures
      summary: Get capture details
      description: >-
        Retrieve the details of a capture. To learn more, refer to the
        [Retrieving capture
        details](https://docs.kustom.co/contents/order-management/manage-orders-with-the-api/capture-and-track-orders#check-the-details-of-a-capture)
        article.
      operationId: getCapture
      parameters:
        - name: order_id
          in: path
          description: Order id
          required: true
          schema:
            type: string
            format: uuid
        - name: capture_id
          in: path
          description: Capture id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Capture found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptureDto'
        '404':
          description: Order or capture not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSuchOrderErrorMessageDto'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                type: string
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        correlation_id:
          type: string
        error_code:
          type: string
          enum:
            - INTERNAL_ERROR
            - NOT_FOUND
            - TOO_MANY_REQUESTS
            - REFUND_NOT_ALLOWED
            - CAPTURE_NOT_ALLOWED
            - CANCEL_NOT_ALLOWED
            - UPDATE_NOT_ALLOWED
            - NO_SUCH_ORDER
            - BAD_REQUEST
            - PAYLOAD_TOO_LARGE
            - NO_SUCH_CAPTURE
            - RESOURCE_NOT_FOUND
            - INVALID_REQUEST_PARAMETERS
            - NOT_ALLOWED
            - UNSUPPORTED_MEDIA_TYPE
            - FORBIDDEN
        error_messages:
          type: array
          items:
            type: string
    AddressDto:
      type: object
      description: Shipping address for the capture.
      properties:
        attention:
          type: string
          description: '''Attn.'' - optional parameter.'
          example: Anders Exempelsson
          maxLength: 255
          minLength: 0
        city:
          type: string
          description: City.
          example: Vetlanda
          maxLength: 200
          minLength: 0
        country:
          type: string
          description: Country. ISO 3166 alpha-2.
          example: se
        email:
          type: string
          description: E-mail address.
          example: john.testsson@kustom.co
          maxLength: 100
          minLength: 0
        family_name:
          type: string
          description: Family name.
          example: Testsson
          maxLength: 100
          minLength: 0
        given_name:
          type: string
          description: Given name.
          example: John
          maxLength: 100
          minLength: 0
        organization_name:
          type: string
          description: >-
            Organization name (if applicable). Only applicable for B2B
            customers.
          example: Kustom
          maxLength: 255
          minLength: 0
        phone:
          type: string
          description: Phone number.
          example: 1-555-555-5555
          maxLength: 100
          minLength: 0
        postal_code:
          type: string
          description: >-
            Postcode. Validation according to [Universal Postal Union addressing
            system](https://www.upu.int/en/activities/addressing/postal-addressing-systems-in-member-countries.html).
          example: 12345
          maxLength: 10
          minLength: 0
        region:
          type: string
          description: State/Region. Required for US.
          example: TN
          maxLength: 200
          minLength: 0
        street_address:
          type: string
          description: >-
            First line of street address. Validation according to [Universal
            Postal Union addressing
            system](https://www.upu.int/en/activities/addressing/postal-addressing-systems-in-member-countries.html)
          example: Testgatan 10
          maxLength: 100
          minLength: 0
        street_address2:
          type: string
          description: Second line of street address.
          example: 1
          maxLength: 100
          minLength: 0
        title:
          type: string
          description: Title.
          example: Herr
          maxLength: 20
          minLength: 0
    OrderLineDto:
      type: object
      description: List of order lines for the capture shown to the customer.
      properties:
        image_url:
          type: string
          description: >-
            URL to an image that can be embedded in communications between
            Klarna and the customer.
          example: https://yourstore.example/product/headphones.png
          maxLength: 1024
          minLength: 0
        merchant_data:
          type: string
          description: Data about the order line.
          example: Some metadata
          maxLength: 1024
          minLength: 0
        name:
          type: string
          description: Descriptive item name.
          maxLength: 255
          minLength: 0
        product_identifiers:
          $ref: '#/components/schemas/ProductIdentifiersDto'
        product_url:
          type: string
          description: >-
            URL to the product that can be used in communications between Klarna
            and the customer.
          example: https://yourstore.example/product/headphones
          maxLength: 1024
          minLength: 0
        quantity:
          type: integer
          format: int64
          description: Item quantity.
          example: 1
          minimum: 0
        quantity_unit:
          type: string
          description: Unit used to describe the quantity.
          example: pcs.
          maxLength: 10
          minLength: 0
        reference:
          type: string
          description: >-
            Article number, SKU, or similar identifier on the product variant
            level.
          example: 75001
          maxLength: 255
          minLength: 0
        tax_rate:
          type: integer
          format: int32
          description: The tax rate in percent with two implicit decimals.
          minimum: 0
        total_amount:
          type: integer
          format: int64
          description: >-
            Total amount including tax and discounts (`quantity * unit_price -
            total_discount_amount`).
          maximum: 200000000
        total_discount_amount:
          type: integer
          format: int64
          description: >-
            The discount amount in minor units. Includes tax. Example: 1200 =
            $12. Max value: 200000000
          example: 0
          maximum: 200000000
          minimum: 0
        total_tax_amount:
          type: integer
          format: int64
          description: The total tax amount in minor units.
          maximum: 200000000
        type:
          type: string
          description: Order line type.
          enum:
            - physical
            - discount
            - shipping_fee
            - sales_tax
            - store_credit
            - gift_card
            - digital
            - surcharge
            - return_fee
            - package
          example: physical
        unit_price:
          type: integer
          format: int64
          description: Unit price including tax without applying discounts in minor units.
          maximum: 200000000
      required:
        - name
        - quantity
        - total_amount
        - unit_price
    ProductIdentifiersDto:
      type: object
      description: product_identifiers
      properties:
        brand:
          type: string
          description: >-
            The product's brand name as generally recognized by consumers. If no
            brand is available for a product, do not supply any value. Maximum
            70 characters. Example: Intel
          example: Intel
          maxLength: 70
          minLength: 0
        category_path:
          type: string
          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 ' > '. Maximum 750 characters. Example: Electronics
            Store > Computers & Tablets > Desktops
          example: Electronics Store > Computers & Tablets > Desktops
          maxLength: 750
          minLength: 0
        color:
          type: string
          description: >-
            Color to be shown to the end customer (max 64 characters). Example:
            Denim blue
          example: Denim blue
          maxLength: 64
          minLength: 0
        global_trade_item_number:
          type: string
          description: >-
            The product's Global Trade Item Number (GTIN). Common types of GTIN
            are EAN, ISBN or UPC. Exclude dashes and spaces, where possible.
            Maximum 50 characters. Example: 735858293167
          example: 735858293167
          maxLength: 50
          minLength: 0
        manufacturer_part_number:
          type: string
          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. Maximum 70
            characters. Example: BOXNUC5CPYH
          example: BOXNUC5CPYH
          maxLength: 70
          minLength: 0
        size:
          type: string
          description: 'Size to be shown to the end customer (max 64 characters). Example: 4'
          example: 4
          maxLength: 64
          minLength: 0
    RefundObjectDto:
      type: object
      properties:
        description:
          type: string
          description: >-
            Description of the refund shown to the customer. Max length is 255
            characters.
          maxLength: 255
          minLength: 0
        order_lines:
          type: array
          description: >-
            Order lines for the refund shown to the customer. Optional but
            increases the customer experience. Maximum 1000 order lines.
          items:
            $ref: '#/components/schemas/OrderLineDto'
          maxItems: 1000
          minItems: 0
        reference:
          type: string
          description: >-
            Internal reference to the refund. This will be included in the
            settlement files. Max length is 255 characters.
          maxLength: 255
          minLength: 0
        refunded_amount:
          type: integer
          format: int64
          description: Refunded amount in minor units.
          maximum: 200000000
          minimum: 0
      required:
        - refunded_amount
    CaptureObjectDto:
      type: object
      description: Capture request data
      properties:
        captured_amount:
          type: integer
          format: int64
          description: The captured amount in minor units.
          maximum: 200000000
          minimum: 0
        description:
          type: string
          description: >-
            Description of the capture shown to the customer. Maximum 255
            characters.
          maxLength: 255
          minLength: 0
        order_lines:
          type: array
          description: Order lines for this capture. Maximum 1000 items.
          items:
            $ref: '#/components/schemas/OrderLineDto'
          maxItems: 1000
          minItems: 0
        reference:
          type: string
          description: >-
            Internal reference to the capture. This will be included in the
            settlement files. Max length is 255 characters.
          maxLength: 255
          minLength: 0
        shipping_delay:
          type: integer
          format: int64
          description: >-
            Delay before the order will be shipped. Use for improving the
            customer experience regarding payments. This field is currently not
            returned when reading the order. Minimum: 0. Please note: to be able
            to submit values larger than 0, this has to be enabled in your
            merchant account. Please contact Kustom for further information.
          minimum: 0
        shipping_info:
          type: array
          description: Shipping information for this capture. Maximum 500 items.
          items:
            $ref: '#/components/schemas/ShippingInfoDto'
          maxItems: 500
          minItems: 0
      required:
        - captured_amount
    ShippingInfoDto:
      type: object
      description: Shipping information for this capture.
      properties:
        return_shipping_company:
          type: string
          description: >-
            Name of the shipping company for the return shipment (as specific as
            possible). Maximum 100 characters. Example: 'DHL SE' and not only
            'DHL'
          example: DHL SE
          maxLength: 100
          minLength: 0
        return_tracking_number:
          type: string
          description: Tracking number for the return shipment. Maximum 100 characters.
          example: 93456415674545680000
          maxLength: 100
          minLength: 0
        return_tracking_uri:
          type: string
          description: >-
            URL where the customer can track the return shipment. Maximum 1024
            characters.
          example: http://shipping.example/findmypackage?93456415674545679888
          maxLength: 1024
          minLength: 0
        shipping_company:
          type: string
          description: >-
            Name of the shipping company (as specific as possible). Maximum 100
            characters. Example: 'DHL SE' and not only 'DHL'
          example: DHL SE
          maxLength: 100
          minLength: 0
        shipping_method:
          type: string
          description: >-
            Shipping method. Allowed values matches
            (PickUpStore|Home|BoxReg|BoxUnreg|PickUpPoint|Own|Postal|DHLPackstation|Digital|Undefined|PickUpWarehouse|ClickCollect|PalletDelivery)
          example: Home
          pattern: >-
            (PickUpStore|Home|BoxReg|BoxUnreg|PickUpPoint|Own|Postal|DHLPackstation|Digital|Undefined|PickUpWarehouse|ClickCollect|PalletDelivery)
        tracking_number:
          type: string
          description: Tracking number for the shipment. Maximum 100 characters.
          example: 63456415674545680000
          maxLength: 100
          minLength: 0
        tracking_uri:
          type: string
          description: >-
            URI where the customer can track their shipment. Maximum 1024
            characters.
          example: http://shipping.example/findmypackage?63456415674545679874
          maxLength: 1024
          minLength: 0
    UpdateShippingInfoDto:
      type: object
      properties:
        shipping_info:
          type: array
          description: 'New shipping info. Maximum: 500 items.'
          items:
            $ref: '#/components/schemas/ShippingInfoDto'
          maxItems: 500
          minItems: 1
      required:
        - shipping_info
    NoSuchOrderErrorMessageDto:
      type: object
      properties:
        correlation_id:
          type: string
          description: Correlation id. For searching logs.
          example: 66782175-ae05-44fc-9eb3-eeceadbad271
        error_code:
          type: string
          description: Error code
          example: NO_SUCH_ORDER
        error_messages:
          type: array
          description: Error messages
          items:
            type: string
    NotAllowedErrorMessageDto:
      type: object
      properties:
        correlation_id:
          type: string
          description: Correlation id. For searching logs.
          example: 66782175-ae05-44fc-9eb3-eeceadbad271
        error_code:
          type: string
          description: Error code
          example: NOT_ALLOWED
        error_messages:
          type: array
          description: Error messages
          items:
            type: string
    RefundNotAllowedErrorMessageDto:
      type: object
      properties:
        correlation_id:
          type: string
          description: Correlation id. For searching logs.
          example: 66782175-ae05-44fc-9eb3-eeceadbad271
        error_code:
          type: string
          description: Error code
          example: REFUND_NOT_ALLOWED
        error_messages:
          type: array
          description: Error messages
          items:
            type: string
    NotFoundErrorMessageDto:
      type: object
      properties:
        correlation_id:
          type: string
          description: Correlation id. For searching logs.
          example: 66782175-ae05-44fc-9eb3-eeceadbad271
        error_code:
          type: string
          description: Error code
          example: NOT_FOUND
        error_messages:
          type: array
          description: Error messages
          items:
            type: string
    CaptureNotAllowedErrorMessageDto:
      type: object
      properties:
        correlation_id:
          type: string
          description: Correlation id. For searching logs.
          example: 66782175-ae05-44fc-9eb3-eeceadbad271
        error_code:
          type: string
          description: Error code
          example: CAPTURE_NOT_ALLOWED
        error_messages:
          type: array
          description: Error messages
          items:
            type: string
    CancelNotAllowedErrorMessageDto:
      type: object
      properties:
        correlation_id:
          type: string
          description: Correlation id. For searching logs.
          example: 66782175-ae05-44fc-9eb3-eeceadbad271
        error_code:
          type: string
          description: Error code
          example: CANCEL_NOT_ALLOWED
        error_messages:
          type: array
          description: Error messages
          items:
            type: string
    UpdateMerchantReferencesDto:
      type: object
      properties:
        merchant_reference1:
          type: string
          description: >-
            New merchant reference 1. Old reference will be overwritten if this
            field is present.
          maxLength: 255
          minLength: 0
        merchant_reference2:
          type: string
          description: >-
            New merchant reference 2. Old reference will be overwritten if this
            field is present.
          maxLength: 255
          minLength: 0
    UpdateConsumerDto:
      type: object
      properties:
        shipping_address:
          $ref: '#/components/schemas/AddressDto'
    UpdateAuthorizationDto:
      type: object
      properties:
        description:
          type: string
          description: Description of the change.
          example: Added charger
          maxLength: 255
          minLength: 0
        order_amount:
          type: integer
          format: int64
          description: The new total order amount. Minor units.
          maximum: 200000000
          minimum: 0
        order_lines:
          type: array
          description: New set of order lines for the order.
          items:
            $ref: '#/components/schemas/OrderLineDto'
          maxItems: 1000
          minItems: 0
      required:
        - order_amount
        - order_lines
    AddonDto:
      type: object
      description: Array consisting of add-ons selected by the consumer, may be empty
      properties:
        external_id:
          type: string
          description: The ID provided by the TMS
        price:
          type: integer
          format: int64
          description: The price of the add-on
          minimum: 0
        type:
          type: string
          description: The type of the add-on, e.g. sms or entry-code
        user_input:
          type: string
          description: The text provided by the user
      required:
        - price
        - type
    CaptureDto:
      type: object
      properties:
        billing_address:
          $ref: '#/components/schemas/AddressDto'
        capture_id:
          type: string
          description: The capture id. Generated when the capture is created.
          example: 4ba29b50-be7b-44f5-a492-113e6a865e22
        captured_amount:
          type: integer
          format: int64
          description: The captured amount in minor units.
          minimum: 1
        captured_at:
          type: string
          format: date-time
          description: The time of the capture. Specified in ISO 8601.
          example: '2025-11-19T01:51:17Z'
        description:
          type: string
          description: Description of the capture shown to the customer.
          example: Order has been shipped
        klarna_reference:
          type: string
          description: >-
            Customer friendly reference id, used as a reference when
            communicating with the customer.
          example: K4MADNY-1
        order_lines:
          type: array
          description: List of order lines for the capture shown to the customer.
          items:
            $ref: '#/components/schemas/OrderLineDto'
        reference:
          type: string
          description: >-
            Internal reference to the capture which will be included in the
            settlement files. Max length is 255 characters.
          maxLength: 255
          minLength: 0
        refunded_amount:
          type: integer
          format: int64
          description: Refunded amount for this capture in minor units.
          example: 0
        shipping_address:
          $ref: '#/components/schemas/AddressDto'
        shipping_info:
          type: array
          description: Shipping information for this capture.
          items:
            $ref: '#/components/schemas/ShippingInfoDto'
    CarrierProductDto:
      type: object
      description: The chosen timeslot of the selected shipping option
      properties:
        identifier:
          type: string
          description: Id of carrier product
        name:
          type: string
          description: Name of carrier product
    CustomerDto:
      type: object
      description: Information about the customer placing the order.
      properties:
        date_of_birth:
          type: string
          format: date
          description: 'The customer date of birth. ISO 8601. '
          example: Sun Sep 06 02:00:00 CEST 1981
        national_identification_number:
          type: string
          description: The customer national identification number
        vat_id:
          type: string
          description: The customer vat Id
        type:
          type: string
          description: The customer type
          enum:
            - person
            - organization
        organization_entity_type:
          type: string
          description: The customer organization entity type
          enum:
            - LIMITED_COMPANY
            - PUBLIC_LIMITED_COMPANY
            - ENTREPRENEURIAL_COMPANY
            - LIMITED_PARTNERSHIP_LIMITED_COMPANY
            - LIMITED_PARTNERSHIP
            - GENERAL_PARTNERSHIP
            - REGISTERED_SOLE_TRADER
            - SOLE_TRADER
            - CIVIL_LAW_PARTNERSHIP
            - PUBLIC_INSTITUTION
            - OTHER
        organization_registration_id:
          type: string
          description: The customer organization registration Id
    InitialPaymentMethodDto:
      type: object
      description: Initial payment method for this order
      properties:
        description:
          type: string
          description: The description of the initial payment method.
          example: Slice it (Fixed Payments)
        number_of_installments:
          type: integer
          format: int32
          description: The number of installments (if applicable).
          example: 3
        type:
          type: string
          description: >-
            The type of the initial payment method. One of BANK_TRANSFER, CARD,
            FIXED_AMOUNT, INVOICE_BUSINESS, INVOICE, MOBILEPAY, PAY_BY_CARD,
            PAY_LATER_IN_PARTS, SWISH, APPLE_PAY_CARD, GOOGLE_PAY_CARD,
            CARTES_BANCAIRES, BLIK, TWINT, BANCONTACT, OTHER
          example: FIXED_AMOUNT
    LocationAddressDto:
      type: object
      description: Address for location
      properties:
        city:
          type: string
          description: City.
          example: Knoxville
          maxLength: 200
          minLength: 0
        country:
          type: string
          description: Country. ISO 3166 alpha-2.
          example: us
        postal_code:
          type: string
          description: >-
            Postcode. Validation according to [Universal Postal Union addressing
            system](https://www.upu.int/en/activities/addressing/postal-addressing-systems-in-member-countries.html).
          example: 12345
          maxLength: 10
          minLength: 0
        region:
          type: string
          description: State/Region. Required for US.
          example: TN
          maxLength: 200
          minLength: 0
        street_address:
          type: string
          description: >-
            First line of street address. Validation according to [Universal
            Postal Union addressing
            system](https://www.upu.int/en/activities/addressing/postal-addressing-systems-in-member-countries.html)
          example: Apartment 10
          maxLength: 100
          minLength: 0
        street_address2:
          type: string
          description: Second line of street address.
          example: 1
          maxLength: 100
          minLength: 0
    LocationDto:
      type: object
      description: The location of the selected shipping option
      properties:
        address:
          $ref: '#/components/schemas/LocationAddressDto'
        id:
          type: string
          description: The location id
        name:
          type: string
          description: The display name of the location
        price:
          type: integer
          format: int64
          description: The price for this location
    MerchantOrderDto:
      type: object
      description: Order
      properties:
        billing_address:
          $ref: '#/components/schemas/AddressDto'
        captured_amount:
          type: integer
          format: int64
          description: The total amount of all captures. In minor units.
          example: 0
        captures:
          type: array
          description: List of captures for this order.
          items:
            $ref: '#/components/schemas/CaptureDto'
        created_at:
          type: string
          format: date-time
          description: The time for the purchase. Formatted according to ISO 8601.
          example: '2025-11-29T10:25:40Z'
        customer:
          $ref: '#/components/schemas/CustomerDto'
        expires_at:
          type: string
          format: date-time
          description: >-
            Order expiration time. The order can only be captured until this
            time. Formatted according to ISO 8601.
          example: '2025-12-04T10:26:06Z'
        fraud_status:
          type: string
          description: Fraud status for the order. Either ACCEPTED, PENDING or REJECTED.
          example: ACCEPTED
        initial_payment_method:
          $ref: '#/components/schemas/InitialPaymentMethodDto'
        klarna_reference:
          type: string
          description: >-
            A Klarna generated reference that is shorter than the Klarna Order
            Id and is used as a customer friendly reference. It is most often
            used as a reference when Klarna is communicating with the customer
            with regard to payment statuses.
          example: K4MADNY
        locale:
          type: string
          description: The customers locale. Specified according to RFC 1766.
          example: en-us
        merchant_data:
          type: string
          description: Text field for storing data about the order. Set at order creation.
          example: Order metadata
        merchant_reference1:
          type: string
          description: >-
            The order number that the merchant should assign to the order. This
            is how a customer would reference the purchase they made. If
            supplied, it is labeled as the Order Number within post purchase
            communications as well as the payment method related apps.
          example: 10001
        merchant_reference2:
          type: string
          description: >-
            Can be used to store your internal reference to the order. This is
            generally an internal reference number that merchants use as
            alternate identifier that matches their internal ERP or Order
            Management system.
          example: 501
        order_amount:
          type: integer
          format: int64
          description: >-
            The order amount in minor units. That is the smallest currency unit
            available such as cent or penny.
        order_id:
          type: string
          description: The unique order ID. Cannot be longer than 255 characters.
          example: f3392f8b-6116-4073-ab96-e330819e2c07
        order_lines:
          type: array
          description: >-
            An array of order_line objects. Each line represents one item in the
            cart.
          items:
            $ref: '#/components/schemas/OrderLineDto'
        original_order_amount:
          type: integer
          format: int64
          description: The original order amount. In minor units.
        purchase_country:
          type: string
          description: The purchase country. Formatted according to ISO 3166-1 alpha-2.
          example: us
        purchase_currency:
          type: string
          description: The currency for this order. Specified in ISO 4217 format.
          example: usd
        refunded_amount:
          type: integer
          format: int64
          description: The total amount of refunded for this order. In minor units.
          example: 0
        refunds:
          type: array
          description: List of refunds for this order.
          items:
            $ref: '#/components/schemas/RefundDto'
        remaining_authorized_amount:
          type: integer
          format: int64
          description: >-
            The remaining authorized amount for this order. To increase the
            `remaining_authorized_amount` the `order_amount` needs to be
            increased.
          example: 0
        selected_shipping_option:
          $ref: '#/components/schemas/SelectedShippingOptionDto'
        shipping_address:
          $ref: '#/components/schemas/AddressDto'
        shipping_info:
          type: array
          description: Shipping information for this order.
          items:
            $ref: '#/components/schemas/ShippingInfoDto'
        status:
          type: string
          description: The order status.
          enum:
            - AUTHORIZED
            - PART_CAPTURED
            - CAPTURED
            - CANCELLED
            - EXPIRED
            - CLOSED
          example: AUTHORIZED
    RefundDto:
      type: object
      properties:
        description:
          type: string
          description: >-
            Description of the refund shown to the customer. Max length is 255
            characters.
          example: The item was returned and the order refunded.
        order_lines:
          type: array
          description: >-
            Order lines for the refund shown to the customer. Optional but
            increases the customer experience. Maximum 1000 order lines.
          items:
            $ref: '#/components/schemas/OrderLineDto'
        reference:
          type: string
          description: >-
            Internal reference to the refund that is also included in the
            settlement files. Max length is 255 characters.
        refund_id:
          type: string
          description: The refund id. Generated when the refund is created.
          example: b2cb4f2e-2781-4359-80ad-555735ebb8d8
        refunded_amount:
          type: integer
          format: int64
          description: Refunded amount in minor units.
        refunded_at:
          type: string
          format: date-time
          description: The time of the refund. ISO 8601.
          example: '2025-12-04T15:17:40Z'
    SelectedShippingOptionDto:
      type: object
      description: The shipping option selected by the user.
      properties:
        carrier:
          type: string
          description: The carrier for the selected shipping option
        carrier_product:
          $ref: '#/components/schemas/CarrierProductDto'
        class:
          type: string
          description: The class of the selected shipping option
        id:
          type: string
          description: The id of the selected shipping option as provided by the TMS
        location:
          $ref: '#/components/schemas/LocationDto'
        method:
          type: string
          description: The method of the selected shipping option
        name:
          type: string
          description: The display name of the selected shipping option
        price:
          type: integer
          format: int64
          description: The price of the selected shipping option
        selected_addons:
          type: array
          description: Array consisting of add-ons selected by the consumer, may be empty
          items:
            $ref: '#/components/schemas/AddonDto'
        tax_amount:
          type: integer
          format: int64
          description: The tax amount of the selected shipping option
        tax_rate:
          type: integer
          format: int64
          description: The tax rate of the selected shipping option
        timeslot:
          $ref: '#/components/schemas/TimeslotDto'
        tms_reference:
          type: string
          description: The shipment_id provided by the TMS
        type:
          type: string
          description: The type of the selected shipping option
    TimeslotDto:
      type: object
      description: The chosen timeslot of the selected shipping option
      properties:
        cutoff:
          type: string
          description: Cutoff time for delivery
        end:
          type: string
          description: End of the timeslot
        id:
          type: string
          description: The timeslot id
        price:
          type: integer
          format: int64
          description: Price
        start:
          type: string
          description: Start of the timeslot
