Klarna Orders API

openapi: 3.0.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:
    UpdateConsumer:
      properties:
        shipping_address:
          $ref: '#/components/schemas/address'
      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
    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
    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
    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
    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
    MerchantOrderDto:
      description: Order
      properties:
        billing_address:
          $ref: '#/components/schemas/address'
        captured_amount:
          description: The total amount of all captures. In minor units.
          example: 0
          format: int64
          type: integer
        captures:
          description: List of captures for this order.
          items:
            $ref: '#/components/schemas/Capture'
          type: array
        created_at:
          description: The time for the purchase. Formatted according to ISO 8601.
          example: '2015-11-29T10:25:40Z'
          format: date-time
          type: string
        customer:
          $ref: '#/components/schemas/customer'
        expires_at:
          description: Order expiration time. The order can only be captured until this time. Formatted according to ISO 8601.
          example: '2015-12-04T10:26:06Z'
          format: date-time
          type: string
        fraud_status:
          description: Fraud status for the order. Either ACCEPTED, PENDING or REJECTED.
          example: ACCEPTED
          type: string
        initial_payment_method:
          $ref: '#/components/schemas/InitialPaymentMethodDto'
        klarna_reference:
          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
          type: string
        locale:
          description: The customers locale. Specified according to RFC 1766.
          example: en-us
          type: string
        merchant_data:
          description: Text field for storing data about the order. Set at order creation.
          example: Order metadata
          type: string
        merchant_reference1:
          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 Klarna App.
          example: '10001'
          type: string
        merchant_reference2:
          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'
          type: string
        order_amount:
          description: The order amount in minor units. That is the smallest currency unit available such as cent or penny.
          format: int64
          type: integer
        order_id:
          description: The unique order ID. Cannot be longer than 255 characters.
          example: f3392f8b-6116-4073-ab96-e330819e2c07
          type: string
        order_lines:
          description: An array of order_line objects. Each line represents one item in the cart.
          items:
            $ref: '#/components/schemas/order_line'
          type: array
        original_order_amount:
          description: The original order amount. In minor units.
          format: int64
          type: integer
        purchase_country:
          description: The purchase country. Formatted according to ISO 3166-1 alpha-2.
          example: us
          type: string
        purchase_currency:
          description: The currency for this order. Specified in ISO 4217 format.
          example: usd
          type: string
        refunded_amount:
          description: The total amount of refunded for this order. In minor units.
          example: 0
          format: int64
          type: integer
        refunds:
          description: List of refunds for this order.
          items:
            $ref: '#/components/schemas/Refund'
          type: array
        remaining_authorized_amount:
          description: The remaining authorized amount for this order. To increase the `remaining_authorized_amount` the `order_amount` needs to be increased.
          example: 0
          format: int64
          type: integer
        selected_shipping_option:
          $ref: '#/components/schemas/SelectedShippingOptionDto'
        shipping_address:
          $ref: '#/components/schemas/address'
        shipping_info:
          description: Shipping information for this order.
          items:
            $ref: '#/components/schemas/shipping_info'
          type: array
        status:
          description: The order status.
          enum:
          - AUTHORIZED
          - PART_CAPTURED
          - CAPTURED
          - CANCELLED
          - EXPIRED
          - CLOSED
          example: AUTHORIZED
          type: string
      type: object
    CarrierProduct:
      description: The chosen timeslot of the selected shipping option
      properties:
        identifier:
          description: Id of carrier product
          type: string
        name:
          description: Name of carrier product
          type: string
      type: object
    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
    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
    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
    Update merchant references:
      properties:
        merchant_reference1:
          description: New merchant reference 1. Old reference will be overwritten if this field is present.
          maxLength: 255
          minLength: 0
          type: string
        merchant_reference2:
          description: New merchant reference 2. Old reference will be overwritten if this field is present.
          maxLength: 255
          minLength: 0
          type: string
      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
    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
    No such order error message:
      properties:
        correlation_id:
          

# --- 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