Billie Order Management API

openapi: 3.2.0
info:
  title: Billie Direct Order Management API
  description: '# Introduction


    With PayAfterDelivery (PAD) / "Rechnungskauf" Billie offers a convenient, secure and simple way to allow your

    B2B-customers to pay on invoice.'
  termsOfService: https://www.billie.io/agb/
  license:
    name: © Billie GmbH, 2020
    url: https://www.billie.io/agb/
  version: v2025.11
  x-logo:
    url: data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDIyLjAuMSwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkViZW5lXzJfS29waWUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIKCSB5PSIwcHgiIHZpZXdCb3g9IjAgMCA0OC41IDY3LjYiIHN0eWxlPSJlbmFibGUtYmFja2dyb3VuZDpuZXcgMCAwIDQ4LjUgNjcuNjsiIHhtbDpzcGFjZT0icHJlc2VydmUiPgo8c3R5bGUgdHlwZT0idGV4dC9jc3MiPgoJLnN0MHtkaXNwbGF5Om5vbmU7ZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS13aWR0aDo3O3N0cm9rZS1taXRlcmxpbWl0OjEwO30KCS5zdDF7ZmlsbDojMUYyNTMwO30KCS5zdDJ7ZmlsbDpub25lO30KCS5zdDN7ZGlzcGxheTpub25lO2VuYWJsZS1iYWNrZ3JvdW5kOm5ldyAgICA7fQoJLnN0NHtmb250LWZhbWlseTonQXZlbmlyTmV4dC1EZW1pQm9sZCc7fQoJLnN0NXtmb250LXNpemU6My4wMzAzcHg7fQoJLnN0NntsZXR0ZXItc3BhY2luZzoyO30KPC9zdHlsZT4KPHBhdGggY2xhc3M9InN0MCIgZD0iTTkuOCw0Ni4xYy0wLjUsMCwyNS4xLTEyLjYsMjUuMS0zMi43YzAtNi45LTUuNi0xMi42LTEyLjYtMTIuNlM5LjcsNi41LDkuNywxMy40TDkuOCw0Ni4xaDE4LjUKCWM2LjksMCwxMi42LTUuNiwxMi42LTEyLjZTMzUuMiwyMSwyOC4yLDIxSDkuNyIvPgo8Zz4KCTxwYXRoIGNsYXNzPSJzdDEiIGQ9Ik0yOC4yLDQ3SDguOHYtMC44YzAtMC4xLDAtMC4yLDAtMC4zVjEzLjVDOC44LDYsMTQuOSwwLDIyLjMsMHMxMy41LDYsMTMuNSwxMy41YzAsMi44LTAuNSw1LjUtMS40LDguMgoJCWM0LjMsMi4yLDcuMyw2LjcsNy4zLDExLjlDNDEuNyw0MSwzNS42LDQ3LDI4LjIsNDd6IE0xMi45LDQ1LjJoMTUuM2M2LjQsMCwxMS43LTUuMywxMS43LTExLjdjMC00LjQtMi41LTguMy02LjEtMTAuMwoJCWMtMS44LDQuNC00LjgsOC43LTksMTIuOEMyMC40LDQwLjQsMTUuOCw0My41LDEyLjksNDUuMnogTTEwLjYsMjEuOXYyMi43YzEzLTcuNywxOC45LTE1LjYsMjEuNS0yMmMtMS4yLTAuNC0yLjUtMC43LTMuOS0wLjdIMTAuNgoJCXogTTEwLjYsMjAuMWgxNy42YzEuNiwwLDMuMSwwLjMsNC41LDAuOGMxLTIuOSwxLjMtNS41LDEuMy03LjRDMzQsNywyOC44LDEuOCwyMi4zLDEuOFMxMC42LDcsMTAuNiwxMy41VjIwLjF6Ii8+CjwvZz4KPHJlY3QgeD0iLTExLjEiIHk9Ii01OC43IiBjbGFzcz0ic3QyIiB3aWR0aD0iODUuNCIgaGVpZ2h0PSI0OS41Ii8+Cjx0ZXh0IHRyYW5zZm9ybT0ibWF0cml4KDEgMCAwIDEgLTEuMDQyNCA2Ny41NzcyKSIgY2xhc3M9InN0MyBzdDQgc3Q1IHN0NiI+QklMTElFPC90ZXh0Pgo8Zz4KCTxwYXRoIGNsYXNzPSJzdDEiIGQ9Ik0wLDU4LjFoMy43YzAuNCwwLDAuNywwLjEsMS4xLDAuMWMwLjQsMC4xLDAuNywwLjIsMC45LDAuNGMwLjMsMC4yLDAuNSwwLjQsMC43LDAuN2MwLjIsMC4zLDAuMywwLjcsMC4zLDEuMQoJCWMwLDAuNS0wLjIsMS0wLjUsMS4zYy0wLjMsMC40LTAuNywwLjYtMS4yLDAuOHYwYzAuNiwwLjEsMS4xLDAuMywxLjUsMC43QzYuOCw2My42LDcsNjQuMiw3LDY0LjhjMCwwLjUtMC4xLDEtMC4zLDEuMwoJCWMtMC4yLDAuNC0wLjUsMC42LTAuOCwwLjljLTAuMywwLjItMC43LDAuNC0xLjIsMC41Yy0wLjQsMC4xLTAuOSwwLjItMS4zLDAuMkgwQzAsNjcuNiwwLDU4LjEsMCw1OC4xeiBNMS43LDYyaDEuNQoJCWMwLjYsMCwxLTAuMSwxLjMtMC4zYzAuMy0wLjIsMC40LTAuNSwwLjQtMWMwLTAuNC0wLjItMC43LTAuNS0wLjljLTAuMy0wLjItMC44LTAuMy0xLjQtMC4zSDEuN0wxLjcsNjJMMS43LDYyeiBNMS43LDY2LjFoMS41CgkJYzAuMiwwLDAuNSwwLDAuNy0wLjFzMC41LTAuMSwwLjctMC4yYzAuMi0wLjEsMC40LTAuMywwLjUtMC40YzAuMS0wLjIsMC4yLTAuNCwwLjItMC44YzAtMC41LTAuMi0wLjktMC41LTEKCQljLTAuMy0wLjItMC45LTAuMy0xLjUtMC4zSDEuN1Y2Ni4xeiIvPgoJPHBhdGggY2xhc3M9InN0MSIgZD0iTTExLjEsNTguMWgxLjd2OS41aC0xLjdWNTguMXoiLz4KCTxwYXRoIGNsYXNzPSJzdDEiIGQ9Ik0xNy4zLDU4LjFoMS43djhoNHYxLjVoLTUuN1Y1OC4xeiIvPgoJPHBhdGggY2xhc3M9InN0MSIgZD0iTTI2LjUsNTguMWgxLjd2OGg0djEuNWgtNS43TDI2LjUsNTguMUwyNi41LDU4LjF6Ii8+Cgk8cGF0aCBjbGFzcz0ic3QxIiBkPSJNMzUuNyw1OC4xaDEuN3Y5LjVoLTEuN1Y1OC4xeiIvPgoJPHBhdGggY2xhc3M9InN0MSIgZD0iTTQxLjksNTguMWg2LjN2MS41aC00LjZWNjJINDh2MS40aC00LjNWNjZoNC44djEuNWgtNi41VjU4LjF6Ii8+CjwvZz4KPC9zdmc+Cg==
    href: '#'
servers:
- url: https://paella-sandbox.billie.io/api/v2
  description: Test Sandbox API
- url: https://paella.billie.io/api/v2
  description: Production API
tags:
- name: Order Management
paths:
  /orders/{id}:
    get:
      tags:
      - Order Management
      summary: Get Order Details
      description: '**Purpose:**


        Retrieves full information about an order.


        **Preconditions:**


        - `id`: The unique identifier of the order


        **Success:**


        - Response Code: `HTTP 200`'
      operationId: order_get_details_v2
      parameters:
      - name: id
        in: path
        description: The unique identifier of the order
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - oauth2: []
    post:
      tags:
      - Order Management
      summary: Update Order
      description: '**Purpose:**


        Updates order information before capture.


        - Adding an external code that represents the order ID of the merchant if not already submitted previously.

        - Changes the order amount associated with the order.


        **Preconditions:**


        - `id`: The unique identifier of the order

        - order is in `state` `created` and does not already has ane `external_code` for an update of ''external_code`

        - order is in `state` `created` or `partially_shipped` for an update of the order amount


        **Success: **


        - Response Code: HTTP 204


        **Attention:**


        - The value provided under `external_code` (the order number from your backend) will be used by Billie in communication with the buyer after capture.

        - If an `external_code` was provided at *create order* or *confirm session* call the uptade order call will fail, if it is a different `external_code`.

        - Lowering the values under the `amount` object to equal the sum of all partial captures will result in the order state to transition from `partially_shipped` to `shipped`.

        - If the update order call increases the amount of the order, the increased amount will be subject to all checks and validations as a newly created order.

        - If any part of the update order call is failing, no changes to the original order will be applied.'
      operationId: order_update_v2
      parameters:
      - name: id
        in: path
        description: The unique identifier of the order.
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrderRequest'
      responses:
        '204':
          description: Order successfully updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - oauth2: []
  /orders/{id}/cancel:
    post:
      tags:
      - Order Management
      summary: Cancel Order
      description: '**Purpose:**


        Cancels an entire order. For cancellations after capture, please see Refunds.


        **Preconditions:**


        - `id`: The unique identifier of the order


        **Success:**


        - Response Code: `HTTP 204`'
      operationId: order_cancel_v2
      parameters:
      - name: id
        in: path
        description: The unique identifier of the order
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '204':
          description: Order successfully cancelled
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - oauth2: []
components:
  schemas:
    UpdateOrderRequest:
      title: Order Update with invoice Object
      properties:
        amount:
          $ref: '#/components/schemas/AmountDTO'
        external_code:
          $ref: '#/components/schemas/TinyText'
      type: object
    OrderDuration:
      title: Order Duration
      type: integer
      maximum: 120
      minimum: 1
      example: 30
    OrderInvoiceResponse:
      title: Order Entity
      properties:
        uuid:
          $ref: '#/components/schemas/UUID'
        invoice_number:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        payout_amount:
          type:
          - number
          - 'null'
          format: float
        amount:
          type: number
          format: float
        amount_net:
          type: number
          format: float
        amount_tax:
          type: number
          format: float
        outstanding_amount:
          type:
          - number
          - 'null'
          format: float
        pending_merchant_payment_amount:
          type:
          - number
          - 'null'
          format: float
        pending_cancellation_amount:
          type:
          - number
          - 'null'
          format: float
        fee_amount:
          type:
          - number
          - 'null'
          format: float
        fee_rate:
          type:
          - number
          - 'null'
          format: float
        due_date:
          type: string
          format: date
          example: '2019-03-20'
        created_at:
          type: string
          format: date
          example: '2019-03-20'
      type: object
    TaxedMoney:
      title: Amount with split values for net, gross and tax.
      required:
      - net
      - gross
      - tax
      properties:
        gross:
          description: Value greater than 0, with max. 2 decimals. It should equal to net + tax.
          type: number
          format: float
          minimum: 1
          example: 260.27
        net:
          description: Value greater than 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 1
          example: 200.12
        tax:
          description: Value greater than or equal to 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 0
          example: 60.15
      type: object
    PaymentMethodCollection:
      title: Eligible Payment Methods
      type: array
      items:
        $ref: '#/components/schemas/PaymentMethod'
    OrderDeclineReason:
      title: Order Decline Reason
      type: string
      enum:
      - risk_policy
      - risk_scoring_failed
      - debtor_not_identified
      - debtor_address
      - risk_scoring_failed
      - debtor_limit_exceeded
      example: debtor_not_identified
    Order:
      title: Order Entity
      properties:
        external_code:
          type:
          - string
          - 'null'
          example: C-10123456789-0001
        uuid:
          $ref: '#/components/schemas/UUID'
        state:
          $ref: '#/components/schemas/OrderStateV2'
        decline_reason:
          $ref: '#/components/schemas/OrderDeclineReason'
        amount:
          $ref: '#/components/schemas/TaxedMoney'
        unshipped_amount:
          $ref: '#/components/schemas/TaxedMoney'
        duration:
          $ref: '#/components/schemas/OrderDuration'
        created_at:
          $ref: '#/components/schemas/DateTime'
        delivery_address:
          $ref: '#/components/schemas/Address'
        debtor:
          $ref: '#/components/schemas/Debtor'
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/OrderInvoiceResponse'
        selected_payment_method:
          type:
          - string
          - 'null'
          enum:
          - bank_transfer
          - direct_debit
          example: bank_transfer
        payment_methods:
          $ref: '#/components/schemas/PaymentMethodCollection'
      type: object
    Address:
      title: Address data are all required except house number.
      required:
      - street
      - postal_code
      - city
      - country
      properties:
        house_number:
          $ref: '#/components/schemas/TinyText'
        street:
          $ref: '#/components/schemas/TinyText'
        postal_code:
          $ref: '#/components/schemas/TinyText'
        city:
          $ref: '#/components/schemas/TinyText'
        country:
          $ref: '#/components/schemas/CountryCode'
      type: object
    ErrorsObject:
      title: API Errors
      properties:
        errors:
          type: array
          items:
            required:
            - title
            - code
            properties:
              title:
                description: Error message
                type: string
              code:
                description: Error code
                type:
                - string
                - 'null'
              source:
                description: Property path where the error occurred, if applicable
                type:
                - string
                - 'null'
            type: object
      type: object
    DateTime:
      title: Date-Time
      type: string
      format: date-time
      example: '2019-01-20 14:00:00'
    DebtorExternalData:
      title: Debtor External Data
      properties:
        merchant_customer_id:
          $ref: '#/components/schemas/TinyText'
        name:
          $ref: '#/components/schemas/TinyText'
        industry_sector:
          type:
          - string
          - 'null'
        address:
          $ref: '#/components/schemas/Address'
      type: object
    Debtor:
      title: Order Debtor
      properties:
        name:
          type: string
          example: C-10123456789-0001
        company_address:
          $ref: '#/components/schemas/Address'
        billing_address:
          $ref: '#/components/schemas/Address'
        bank_account:
          $ref: '#/components/schemas/BankAccount'
        external_data:
          $ref: '#/components/schemas/DebtorExternalData'
      type: object
    TinyText:
      title: string
      type: string
      maxLength: 255
    BankAccount:
      title: Simple representation of a bank account
      properties:
        iban:
          $ref: '#/components/schemas/TinyText'
        bic:
          $ref: '#/components/schemas/TinyText'
      type: object
    PaymentMethodType:
      title: Payment Method Type
      type: string
      enum:
      - bank_transfer
      - direct_debit
      example: bank_transfer
    CountryCode:
      title: Country Code
      description: 'ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2'
      type: string
      maxLength: 2
      minLength: 2
      example: DE
    PaymentMethod:
      title: Payment Method
      properties:
        type:
          $ref: '#/components/schemas/PaymentMethodType'
        data:
          description: Payment method details
          properties:
            iban:
              $ref: '#/components/schemas/TinyText'
            bic:
              $ref: '#/components/schemas/TinyText'
            bank_name:
              description: Name of the Bank entity
              type:
              - string
              - 'null'
            bank_giro:
              description: Bank giro number (Sweden only)
              type:
              - string
              - 'null'
            sort_code:
              description: Bank sort code (GB only)
              type:
              - string
              - 'null'
            account_number:
              description: Bank account number (GB, NL and NO)
              type:
              - string
              - 'null'
            bank_account_owner:
              description: Bank account owner entity
              type: string
            mandate_reference:
              description: Direct Debit SEPA Mandate Reference (for Direct Debit only)
              type:
              - string
              - 'null'
            mandate_execution_date:
              $ref: '#/components/schemas/DateTime'
            creditor_identification:
              description: Creditor Identification Code (for Direct Debit only)
              type:
              - string
              - 'null'
          type: object
      type: object
    OrderStateV2:
      title: Order State
      type: string
      enum:
      - pre_waiting
      - authorized
      - waiting
      - created
      - declined
      - shipped
      - partially_shipped
      - complete
      - canceled
      example: created
    UUID:
      type: string
      format: uuid
      maxLength: 36
      minLength: 36
      example: 12345667-890a-bcde-f123-34567890abcd
    AmountDTO:
      title: object <net, gross, tax>
      description: The amount object with split values for net, gross and tax
      required:
      - net
      - gross
      - tax
      properties:
        gross:
          description: Value greater than 0, with max. 2 decimals. It should equal to net + tax.
          type: number
          format: float
          minimum: 0.01
          example: 260.27
        net:
          description: Value greater than 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 0.01
          example: 200.12
        tax:
          description: Value greater than or equal to 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 0
          example: 60.15
      type: object
  responses:
    ServerError:
      description: Unexpected Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsObject'
    Unauthorized:
      description: Unauthorized request or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsObject'
    BadRequest:
      description: Invalid Request Data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsObject'
    NotFound:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsObject'
    Forbidden:
      description: Forbidden Request. The operation cannot be completed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsObject'
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'This authentication mechanism is based on the OAuth 2.0 prototocol and requires a Client ID, a Client Secret Key and

        in some cases also a user and password.


        With these credentials, the client should request a token using the `POST /api/v1/oauth/token` endpoint,

        which should be used in the `Authorization` header together with the `Bearer` challenge to authenticate all the requests.


        > Example: `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c`.'
      flows:
        password:
          tokenUrl: /oauth/token
          scopes:
            default: default
x-provenance:
  method: searched
  source: https://docs.billie.io/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.billie.io/reference/confirm_authorization_v2.md
  - https://docs.billie.io/reference/create_checkout_session_v2.md
  - https://docs.billie.io/reference/create_credit_note.md
  - https://docs.billie.io/reference/create_hpp_checkout_session_v2.md
  - https://docs.billie.io/reference/get_checkout_session_authorization_v2.md
  - https://docs.billie.io/reference/get_invoice.md
  - https://docs.billie.io/reference/get_legal_forms.md
  - https://docs.billie.io/reference/invoice_cancel_v2.md
  - https://docs.billie.io/reference/invoice_create.md
  - https://docs.billie.io/reference/invoice_payment_confirm.md
  - https://docs.billie.io/reference/invoice_update.md
  - https://docs.billie.io/reference/oauth_token_create.md
  - https://docs.billie.io/reference/oauth_token_revoke.md
  - https://docs.billie.io/reference/oauth_token_validate.md
  - https://docs.billie.io/reference/order_cancel_v2.md
  - https://docs.billie.io/reference/order_create_v2.md
  - https://docs.billie.io/reference/order_get_details_v2.md
  - https://docs.billie.io/reference/order_update_v2.md
  merge:
    pages: 18
    deduped: 152
    conflicts_kept_first: 0