Klarna Orders API

openapi: 3.2.0
info:
  description: Hosted Payment Page (HPP) API is a service that lets you integrate Klarna Payments without the need of hosting the web page that manages the client side of Klarna Payments.
  version: '1.1'
  title: Klarna HPP Captures Orders API
  license:
    name: Klarna Bank AB
servers:
- url: https://api.klarna.com
tags:
- name: Orders
paths:
  /ordermanagement/v1/orders/{order_id}:
    get:
      description: An order that has the given order id. Read more on [Retrieving order details](https://docs.klarna.com/order-management/pre-delivery/order-details/)
      operationId: getOrder
      parameters:
      - description: Order id
        in: path
        name: order_id
        required: true
        schema:
          type: string
      - in: header
        name: Klarna-Integrator
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantOrderDto'
          description: Order found
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/No_such_order_error_message'
          description: Order not found
      security:
      - basicAuth: []
      summary: Klarna Get order details
      tags:
      - Orders
  /ordermanagement/v1/orders/{order_id}/acknowledge:
    post:
      description: Acknowledge order. Read more on [Acknowledging orders](https://docs.klarna.com/order-management/pre-delivery/acknowledge-kco-order/)
      operationId: acknowledgeOrder
      parameters:
      - description: Order id
        in: path
        name: order_id
        required: true
        schema:
          type: string
      - 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.
        in: header
        name: Klarna-Idempotency-Key
        schema:
          type: string
      responses:
        '204':
          description: Order was acknowledged.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Not_allowed_error_message'
          description: Update not allowed.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/No_such_order_error_message'
          description: Order not found.
      security:
      - basicAuth: []
      summary: Acknowledge a Klarna checkout order
      tags:
      - Orders
  /ordermanagement/v1/orders/{order_id}/authorization:
    patch:
      description: Set new order amount and order lines. Read more on [Updating orders](https://docs.klarna.com/order-management/pre-delivery/update-order-amount/)
      operationId: updateAuthorization
      parameters:
      - description: Order id
        in: path
        name: order_id
        required: true
        schema:
          type: string
      - 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.
        in: header
        name: Klarna-Idempotency-Key
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Update_authorization'
        required: true
      responses:
        '204':
          content:
            application/json:
              schema:
                type: string
          description: Authorization was updated.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Not_allowed_error_message'
          description: Update authorization not allowed. Decision is based on order state and outcome of risk assessment.
      security:
      - basicAuth: []
      summary: Klarna Update the order amount and order lines
      tags:
      - Orders
  /ordermanagement/v1/orders/{order_id}/customer-details:
    patch:
      description: Update shipping address. Read more on [Updating customer addresses](https://docs.klarna.com/order-management/pre-delivery/update-customer-address/)
      operationId: updateConsumerDetails
      parameters:
      - description: Order id
        in: path
        name: order_id
        required: true
        schema:
          type: string
      - 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.
        in: header
        name: Klarna-Idempotency-Key
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConsumer'
        required: true
      responses:
        '204':
          content:
            application/json:
              schema:
                type: string
          description: Order consumer details were updated.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Not_allowed_error_message'
          description: Update customer details not allowed. Decision is based on order state and outcome of risk assessment. Billing address cannot be updated.
      security:
      - basicAuth: []
      summary: Klarna Update customer addresses
      tags:
      - Orders
  /ordermanagement/v1/orders/{order_id}/extend-authorization-time:
    post:
      description: Extend authorization time. Read more on [Extending order authorization time](https://docs.klarna.com/order-management/pre-delivery/extend-order-authorization-time/)
      operationId: extendAuthorizationTime
      parameters:
      - description: Order id
        in: path
        name: order_id
        required: true
        schema:
          type: string
      - 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.
        in: header
        name: Klarna-Idempotency-Key
        schema:
          type: string
      responses:
        '204':
          description: Authorization time was extended.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Not_allowed_error_message'
          description: Extension of authorization time not allowed. The order being expired or cancelled are among the possible causes.
      security:
      - basicAuth: []
      summary: Klarna Extend the authorization time
      tags:
      - Orders
  /ordermanagement/v1/orders/{order_id}/merchant-references:
    patch:
      description: Update merchant references. Read more on [Updating merchant references](https://docs.klarna.com/order-management/pre-delivery/update-merchant-references/)
      operationId: updateMerchantReferences
      parameters:
      - description: Order id
        in: path
        name: order_id
        required: true
        schema:
          type: string
      - 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.
        in: header
        name: Klarna-Idempotency-Key
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Update_merchant_references'
        required: true
      responses:
        '204':
          description: Order merchant references were updated.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Not_allowed_error_message'
          description: Can not update a cancelled order.
      security:
      - basicAuth: []
      summary: Klarna Update merchant references
      tags:
      - Orders
  /ordermanagement/v1/orders/{order_id}/release-remaining-authorization:
    post:
      description: Release remaining authorization. Read more on [Releasing remaining authorization](https://docs.klarna.com/order-management/post-delivery/release-remaining-authorization/)
      operationId: releaseRemainingAuthorization
      parameters:
      - description: Order id
        in: path
        name: order_id
        required: true
        schema:
          type: string
      - 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.
        in: header
        name: Klarna-Idempotency-Key
        schema:
          type: string
      responses:
        '204':
          content:
            application/json:
              schema:
                type: string
          description: Remaining authorization was released.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Not_allowed_error_message'
          description: Can not release when order is cancelled or has no captures.
      security:
      - basicAuth: []
      summary: Klarna Release an authorization
      tags:
      - Orders
  /ordermanagement/v1/orders/{order_id}/shipping-info:
    post:
      description: Add shipping info to an order. Read more on [Adding shipping info](https://docs.klarna.com/order-management/manage-orders-with-the-api/view-and-change-orders/add-shipping-information/)
      operationId: appendOrderShippingInfo
      parameters:
      - description: Order id
        in: path
        name: order_id
        required: true
        schema:
          type: string
      - 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.
        in: header
        name: Klarna-Idempotency-Key
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateShippingInfo'
        required: true
      responses:
        '204':
          description: Shipping information was appended.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/No_such_order_error_message'
          description: Order not found.
      security:
      - basicAuth: []
      summary: Klarna Add shipping information
      tags:
      - Orders
  /ordermanagement/v1/orders/{order_id}/cancel:
    post:
      description: Cancel order. Read more on [Cancelling an order](https://docs.klarna.com/order-management/pre-delivery/cancel-order/)
      operationId: cancelOrder
      parameters:
      - description: Order id
        in: path
        name: order_id
        required: true
        schema:
          type: string
      - 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.
        in: header
        name: Klarna-Idempotency-Key
        schema:
          type: string
      responses:
        '204':
          description: Order was cancelled.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cancel_not_allowed_error_message'
          description: Cancel not allowed (e.g. order has captures or is closed)
      security:
      - basicAuth: []
      summary: Klarna Cancel an order
      tags:
      - Orders
components:
  schemas:
    shipping_info:
      description: Shipping information for this capture.
      properties:
        return_shipping_company:
          description: 'Name of the shipping company for the return shipment (as specific as possible). Maximum 100 characters. Example: ''DHL US'' and not only ''DHL'''
          example: DHL US
          maxLength: 100
          minLength: 0
          type: string
        return_tracking_number:
          description: Tracking number for the return shipment. Maximum 100 characters.
          example: '93456415674545679888'
          maxLength: 100
          minLength: 0
          type: string
        return_tracking_uri:
          description: URL where the customer can track the return shipment. Maximum 1024 characters.
          example: http://shipping.example/findmypackage?93456415674545679888
          maxLength: 1024
          minLength: 0
          type: string
        shipping_company:
          description: 'Name of the shipping company (as specific as possible). Maximum 100 characters. Example: ''DHL US'' and not only ''DHL'''
          example: DHL US
          maxLength: 100
          minLength: 0
          type: string
        shipping_method:
          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)
          type: string
        tracking_number:
          description: Tracking number for the shipment. Maximum 100 characters.
          example: '63456415674545679874'
          maxLength: 100
          minLength: 0
          type: string
        tracking_uri:
          description: URI where the customer can track their shipment. Maximum 1024 characters.
          example: http://shipping.example/findmypackage?63456415674545679874
          maxLength: 1024
          minLength: 0
          type: string
      type: object
    UpdateConsumer:
      properties:
        shipping_address:
          $ref: '#/components/schemas/address'
      type: object
    InitialPaymentMethodDto:
      description: Initial payment method for this order
      properties:
        description:
          description: The description of the initial payment method.
          example: Slice it (Fixed Payments)
          type: string
        number_of_installments:
          description: The number of installments (if applicable).
          example: 3
          format: int32
          type: integer
        type:
          description: The type of the initial payment method. One of ACCOUNT, ALTERNATIVE_PAYMENT_METHOD, BANK_TRANSFER, CARD, DEFERRED_INTEREST, DIRECT_DEBIT, FIXED_AMOUNT_BY_CARD, FIXED_AMOUNT, FIXED_SUM_CREDIT, INVOICE_BUSINESS, INVOICE, MOBILEPAY, PAY_BY_CARD, PAY_IN_X, PAY_LATER_BY_CARD, PAY_LATER_IN_PARTS, SWISH, OTHER
          example: FIXED_AMOUNT
          type: string
      type: object
    address:
      description: Shipping address for the capture.
      properties:
        attention:
          description: '''Attn.'' - optional parameter.'
          example: John Smith
          maxLength: 255
          minLength: 0
          type: string
        city:
          description: City.
          example: Knoxville
          maxLength: 200
          minLength: 0
          type: string
        country:
          description: Country. ISO 3166 alpha-2.
          example: us
          type: string
        email:
          description: E-mail address.
          example: klara.joyce@klarna.com
          maxLength: 100
          minLength: 0
          type: string
        family_name:
          description: Family name.
          example: Joyce
          maxLength: 100
          minLength: 0
          type: string
        given_name:
          description: Given name.
          example: Klara
          maxLength: 100
          minLength: 0
          type: string
        organization_name:
          description: Organization name (if applicable). Only applicable for B2B customers.
          example: Klarna
          maxLength: 255
          minLength: 0
          type: string
        phone:
          description: Phone number.
          example: 1-555-555-5555
          maxLength: 100
          minLength: 0
          type: string
        postal_code:
          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
          type: string
        region:
          description: State/Region. Required for US.
          example: TN
          maxLength: 200
          minLength: 0
          type: string
        street_address:
          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
          type: string
        street_address2:
          description: Second line of street address.
          example: 1 Safeway
          maxLength: 100
          minLength: 0
          type: string
        title:
          description: Title.
          example: Mrs
          maxLength: 20
          minLength: 0
          type: string
      type: object
    SelectedShippingOptionDto:
      description: The shipping option selected by the user.
      properties:
        carrier:
          description: The carrier for the selected shipping option
          type: string
        carrier_product:
          $ref: '#/components/schemas/CarrierProduct'
        class:
          description: The class of the selected shipping option
          type: string
        id:
          description: The id of the selected shipping option as provided by the TMS
          type: string
        location:
          $ref: '#/components/schemas/Location'
        method:
          description: The method of the selected shipping option
          type: string
        name:
          description: The display name of the selected shipping option
          type: string
        price:
          description: The price of the selected shipping option
          enum:
          - null
          format: int64
          type: integer
        selected_addons:
          description: Array consisting of add-ons selected by the consumer, may be empty
          items:
            $ref: '#/components/schemas/Addon'
          type: array
        tax_amount:
          description: The tax amount of the selected shipping option
          enum:
          - null
          format: int64
          type: integer
        tax_rate:
          description: The tax rate of the selected shipping option
          enum:
          - null
          format: int64
          type: integer
        timeslot:
          $ref: '#/components/schemas/Timeslot'
        tms_reference:
          description: The shipment_id provided by the TMS
          type: string
        type:
          description: The type of the selected shipping option
          type: string
      type: object
    Capture:
      properties:
        billing_address:
          $ref: '#/components/schemas/address'
        capture_id:
          description: The capture id. Generated when the capture is created.
          example: 4ba29b50-be7b-44f5-a492-113e6a865e22
          type: string
        captured_amount:
          description: The captured amount in minor units.
          format: int64
          minimum: 1
          type: integer
        captured_at:
          description: The time of the capture. Specified in ISO 8601.
          example: '2015-11-19T01:51:17Z'
          format: date-time
          type: string
        description:
          description: Description of the capture shown to the customer.
          example: Order has been shipped
          type: string
        klarna_reference:
          description: Customer friendly reference id, used as a reference when communicating with the customer.
          example: K4MADNY-1
          type: string
        order_lines:
          description: List of order lines for the capture shown to the customer.
          items:
            $ref: '#/components/schemas/order_line'
          type: array
        reference:
          description: Internal reference to the capture which will be included in the settlement files. Max length is 255 characters.
          maxLength: 255
          minLength: 0
          type: string
        refunded_amount:
          description: Refunded amount for this capture in minor units.
          example: 0
          format: int64
          type: integer
        shipping_address:
          $ref: '#/components/schemas/address'
        shipping_info:
          description: Shipping information for this capture.
          items:
            $ref: '#/components/schemas/shipping_info'
          type: array
      type: object
    Address:
      description: The address of the location
      properties:
        city:
          description: City
          type: string
        country:
          description: Country
          type: string
        postal_code:
          description: Postal code. Validation according to [Universal Postal Union addressing system](https://www.upu.int/en/activities/addressing/postal-addressing-systems-in-member-countries.html).
          type: string
        region:
          description: Region
          type: string
        street_address:
          description: The street address. Validation according to [Universal Postal Union addressing system](https://www.upu.int/en/activities/addressing/postal-addressing-systems-in-member-countries.html)
          type: string
        street_address__2:
          description: Additional street address
          type: string
      required:
      - country
      - street_address
      type: object
    Refund:
      properties:
        credit_invoice:
          description: Only relevant for B2B Orders. If the flag is set to true for an order with B2B_invoice as payment method, the customer will receive the refund as a credit invoice.
          type: boolean
        description:
          description: Description of the refund shown to the customer. Max length is 255 characters.
          example: The item was returned and the order refunded.
          type: string
        order_lines:
          description: Order lines for the refund shown to the customer. Optional but increases the customer experience. Maximum 1000 order lines.
          items:
            $ref: '#/components/schemas/order_line'
          type: array
        reference:
          description: Internal reference to the refund that is also included in the settlement files. Max length is 255 characters.
          type: string
        refund_id:
          description: The refund id. Generated when the refund is created.
          example: b2cb4f2e-2781-4359-80ad-555735ebb8d8
          type: string
        refunded_amount:
          description: Refunded amount in minor units.
          format: int64
          type: integer
        refunded_at:
          description: The time of the refund. ISO 8601.
          example: '2015-12-04T15:17:40Z'
          format: date-time
          type: string
      type: object
    Cancel_not_allowed_error_message:
      properties:
        correlation_id:
          description: Correlation id. For searching logs.
          example: 66782175-ae05-44fc-9eb3-eeceadbad271
          type: string
        error_code:
          description: Error code
          example: CANCEL_NOT_ALLOWED
          type: string
        error_messages:
          description: Error messages
          items:
            description: Error messages
            type: string
          type: array
      type: object
    Addon:
      description: Array consisting of add-ons selected by the consumer, may be empty
      properties:
        external_id:
          description: The ID provided by the TMS
          type: string
        price:
          description: The price of the add-on
          enum:
          - null
          format: int64
          minimum: 0
          type: integer
        type:
          description: The type of the add-on, e.g. sms or entry-code
          type: string
        user_input:
          description: The text provided by the user
          type: string
      required:
      - price
      - type
      type: object
    Update_authorization:
      properties:
        description:
          description: Description of the change.
          example: Added charger
          maxLength: 255
          minLength: 0
          type: string
        order_amount:
          description: The new total order amount. Minor units.
          format: int64
          maximum: 200000000
          minimum: 0
          type: integer
        order_lines:
          description: New set of order lines for the order.
          items:
            $ref: '#/components/schemas/order_line'
          maxItems: 1000
          minItems: 0
          type: array
      required:
      - order_amount
      type: object
    No_such_order_error_message:
      properties:
        correlation_id:
          description: Correlation id. For searching logs.
          example: 66782175-ae05-44fc-9eb3-eeceadbad271
          type: string
        error_code:
          description: Error code
          example: NO_SUCH_ORDER
          type: string
        error_messages:
          description: Error messages
          items:
            description: Error messages
            type: string
          type: array
      type: object
    subscription:
      description: Subscription information, such as the cadence and product name of the subscription that an order line item belongs to.
      properties:
        interval:
          description: 'The cadence unit. Matches: DAY|WEEK|MONTH|YEAR'
          example: MONTH
          pattern: DAY|WEEK|MONTH|YEAR
          type: string
        interval_count:
          description: The number of intervals.
          format: int32
          minimum: 1
          type: integer
        name:
          description: The name of the subscription product. Maximum 255 characters.
          maxLength: 255
          minLength: 0
          type: string
      required:
      - interval
      - interval_count
      - name
      type: object
    Not_allowed_error_message:
      properties:
        correlation_id:
          description: Correlation id. For searching logs.
          example: 66782175-ae05-44fc-9eb3-eeceadbad271
          type: string
        error_code:
          description: Error code
          example: NOT_ALLOWED
          type: string
        error_messages:
          description: Error messages
          items:
            description: Error messages
            type: string
          type: array
      type: object
    order_line:
      description: List of order lines for the capture shown to the customer.
      properties:
        image_url:
          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
          type: string
        merchant_data:
          description: Data about the order line.
          example: Some metadata
          maxLength: 1024
          minLength: 0
          type: string
        name:
          description: Descriptive item name.
          maxLength: 255
          minLength: 0
          type: string
        product_identifiers:
          $ref: '#/components/schemas/ProductIdentifiers'
        product_url:
          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
          type: string
        quantity:
          description: Item quantity.
          example: 1
          format: int64
          minimum: 0
          type: integer
        quantity_unit:
          description: Unit used to describe the quantity.
          example: pcs.
          maxLength: 10
          minLength: 0
          type: string
        reference:
          description: Article number, SKU, or similar identifier on the product variant level.
          example: '75001'
          maxLength: 255
          minLength: 0
          type: string
        subscription:
          $ref: '#/components/schemas/subscription'
        tax_rate:
          description: The tax rate in percent with two implicit decimals.
          format: int32
          minimum: 0
          type: integer
        total_amount:
          description: Total amount including tax and discounts (`quantity * unit_price - total_discount_amount`).
          format: int64
          maximum: 200000000
          type: integer
        total_discount_amount:
          description: 'The discount amount in minor units. Includes tax. Example: 1200 = $12. Max value: 200000000'
          example: 0
          format: int64
          maximum: 200000000
          minimum: 0
          type: integer
        total_tax_amount:
          description: The total tax amount in minor units.
          format: int64
          maximum: 200000000
          type: integer
        type:
          description: Order line type.
          enum:
          - physical|discount|shipping_fee|sales_tax|store_credit|gift_card|digital|surcharge|return_fee
          example: physical
          pattern: physical|discount|shipping_fee|sales_tax|store_credit|gift_card|digital|surcharge|return_fee
          type: string
        unit_price:
          description: Unit price including tax without applying discounts in minor units.
          format: int64
          maximum: 200000000
          type: integer
      required:
      - name
      - quantity
      - total_amount
      - unit_price
      type: object
    UpdateShippingInfo:
      properties:
        shipping_info:
          description: 'New shipping info. Maximum: 500 items.'
          items:
            $ref: '#/components/schemas/shipping_info'
          maxItems: 500
          minItems: 1
          type: array
      required:
      - shipping_info
      type: object
    Timeslot:
      description: The chosen timeslot of the selected shipping option
      properties:
        cutoff:
          description: Cutoff time for delivery
          type: string
        end:
          description: End of the timeslot
          type: string
        id:
          description: The timeslot id
          type: string
        price:
          description: Price
          enum:
          - null
          format: int64
          type: integer
        start:
          description: Start of the timeslot
          type: string
      type: object
    ProductIdentifiers:
      description: product_identifiers
      properties:
        brand:
          description: 'The product''s brand name as generally recogni

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/klarna/refs/heads/main/openapi/klarna-orders-api-openapi.yml