> ## Documentation Index
> Fetch the complete documentation index at: https://learn.breezing.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Match Invoice Payment API

> Link a Breezing transaction to the received invoice it paid, settling it against Accounts Payable when the invoice is approved.



## OpenAPI

````yaml POST /invoices/{id}/match
openapi: 3.1.0
info:
  title: Breezing Public API
  version: 1.0.0
  description: >-
    Crypto accounting API for programmatic access and AI agents. Authenticate
    with an API key using the Authorization header: `Bearer brz_...`
servers:
  - url: https://api.breezing.io/v1
security:
  - BearerAuth: []
paths:
  /invoices/{id}/match:
    post:
      tags:
        - Invoices
      summary: Link a payment transaction
      description: >-
        Record that a transaction paid this invoice (a Payment Match). The
        transaction must exist in this company (404 otherwise). Linking is
        idempotent: an existing pair is not duplicated. On an APPROVED invoice
        the transaction is settled in the same call: coded to the Accounts
        Payable account, or to the AP clearing account when the company has one
        (vat = no-vat, history saved before the write), and outside clearing
        mode allocated against what the invoice still owes. Locked or processing
        rows, and a transaction that cannot be applied (worth more than the
        invoices linked to it, not priced, wrong direction), keep their coding
        and come back as warnings. When the invoice is already published at
        Xero, the payment is recorded there in the same call (payments). On a
        REVIEW invoice the transaction takes the invoice's GL account and VAT
        rate instead (codingApplied), so a linked payment is coded the way the
        invoice is without a separate apply call. 409 when the transaction is
        already linked to an issued invoice (one payment settles one side), and
        on an approved invoice when the Books Lock Date covers the transaction's
        day or the link would move the invoice's settlement entry out of the
        locked period.
      parameters:
        - schema:
            type: string
            description: Invoice ID
            example: '42'
          required: true
          description: Invoice ID
          name: id
          in: path
        - schema:
            type: string
            description: >-
              Organization ID. Use GET /v1/companies to discover available
              org/company pairs.
            example: '1'
          required: true
          description: >-
            Organization ID. Use GET /v1/companies to discover available
            org/company pairs.
          name: orgId
          in: query
        - schema:
            type: string
            description: >-
              Company ID. Use GET /v1/companies to discover available companies
              and their access levels.
            example: '1'
          required: true
          description: >-
            Company ID. Use GET /v1/companies to discover available companies
            and their access levels.
          name: companyId
          in: query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceTransactionBody'
      responses:
        '200':
          description: Transaction linked
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      added:
                        type: integer
                      settled:
                        type: boolean
                        description: >-
                          True when the invoice is approved and the transaction
                          was settled in the same call: re-coded to the
                          settlement account and, outside clearing mode, given
                          its allocation (how much of the invoice it pays).
                      settlementMode:
                        type: string
                        nullable: true
                        enum:
                          - direct
                          - clearing
                          - none
                          - null
                        description: >-
                          How the company settles invoices, null when the call
                          settled nothing (a review invoice). direct = the
                          transaction is coded to the Accounts Payable account;
                          clearing = to the AP Clearing account (the QuickBooks
                          loop); none = the company has no Accounts Payable
                          account, so the transaction keeps its coding.
                      payments:
                        type: array
                        items:
                          $ref: '#/components/schemas/InvoiceMatchPayment'
                        description: >-
                          Xero direct settlement on an invoice that is already
                          published: the payment recorded at Xero for this link
                          in the same call. Empty otherwise.
                      codingApplied:
                        type: boolean
                        description: >-
                          True when the invoice is in review and its GL account
                          / VAT rate were stamped onto the transaction in the
                          same call (coding follows the invoice; false when the
                          invoice carries no coding or the row already had it).
                      warnings:
                        type: array
                        items:
                          type: string
                        description: >-
                          Non-fatal notes (a locked transaction that kept its
                          coding, an unset AP Clearing account, ...).
                    required:
                      - added
                      - settled
                      - settlementMode
                      - payments
                      - codingApplied
                      - warnings
                required:
                  - success
                  - data
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '403':
          description: >-
            API key has no access to this company, has read-only access where
            write was required, or the company subscription is inactive
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '404':
          description: Invoice or transaction not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '409':
          description: The transaction pays an issued invoice, or the books are locked
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
      security:
        - BearerAuth: []
components:
  schemas:
    InvoiceTransactionBody:
      type: object
      properties:
        trxId:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          description: Breezing transaction ID (the internal id, not the hash).
      required:
        - trxId
    InvoiceMatchPayment:
      type: object
      properties:
        trxId:
          type: number
        status:
          type: string
          enum:
            - recorded
            - alreadyRecorded
            - skipped
            - failed
        accountCode:
          type: string
          nullable: true
          description: The asset account of the transaction the payment draws on.
        amount:
          type: string
          nullable: true
        paymentId:
          type: string
          nullable: true
        reason:
          type: string
          nullable: true
          description: Why the match was skipped or refused, null otherwise.
      required:
        - trxId
        - status
        - accountCode
        - amount
        - paymentId
        - reason

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.