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

# Publish Invoice API

> Publish an approved Breezing invoice to Xero or QuickBooks as a purchase bill and record its payment from the matched transactions.



## OpenAPI

````yaml POST /invoices/{id}/publish
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}/publish:
    post:
      tags:
        - Invoices
      summary: Publish an approved invoice as a provider bill
      description: >-
        Post the invoice to Xero or QuickBooks as a purchase bill (Dr expense /
        Cr accounts payable at the provider) and record its payment.


        Xero, direct settlement: ONE payment per matched transaction, from the
        own asset account of that transaction, dated its day, for the amount its
        allocation applied (reference "[BREEZING:<transaction id>]<hash>"). The
        response lists one outcome per transaction in payments. A transaction is
        skipped, with the reason, when it is locked or processing, a trade leg
        or an internal transfer, on an account Xero types as BANK, or when the
        bill is in another currency than the company currency; those are paid
        from the transaction dialog instead. The transaction then syncs to Xero
        with its fee and gain or loss only, never its amount.


        QuickBooks, and any company with an AP clearing account: one payment for
        the bill total from the clearing account (Dr AP / Cr AP clearing), and
        the payment transaction coded to clearing closes the loop.


        The original document is attached to the bill on first publish.
        Re-publishing updates the same bill in place.


        Requirements (400 with the reason otherwise): approved status, a
        bookable documentType (credit notes are not published), vendorName,
        invoiceDate, currency, a positive totalAmount, a GL account, the
        provider connected. A tax rate mapped to a provider tax code (PATCH
        /taxes) rides the bill line; unmapped rates keep the provider account
        default. Course organizations cannot publish. Payment failures degrade
        to payment "failed" with the reason (for example a Xero account without
        "Enable payments to this account"); the bill stands. Provider-side
        validation errors on the bill come back as 400 with the provider
        message.


        The same invoice maps to ONE bill, updated in place, and a payment
        already recorded is never recorded twice. Two calls running at the same
        time can still each create a bill: never retry a publish that has not
        answered yet, read GET /invoices/{id} first.
      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/InvoiceProviderBody'
      responses:
        '200':
          description: Bill published
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      published:
                        type: boolean
                        enum:
                          - true
                      provider:
                        type: string
                        enum:
                          - xero
                          - qbo
                      billId:
                        type: string
                      updatedExisting:
                        type: boolean
                        description: True when an existing bill was updated in place.
                      payment:
                        type: string
                        description: >-
                          The payment step in one word: recorded |
                          alreadyRecorded | noMatches | skipped | failed (and
                          noClearingAccount for a QuickBooks company without
                          one). For Xero direct settlement it summarizes the
                          payments list.
                      paymentError:
                        type: string
                        nullable: true
                      settlementMode:
                        type: string
                        enum:
                          - direct
                          - clearing
                          - none
                        description: 'Xero only: how the bill was paid.'
                      payments:
                        type: array
                        items:
                          $ref: '#/components/schemas/InvoiceMatchPayment'
                        description: >-
                          Xero direct settlement: one outcome per matched
                          transaction. Empty in clearing mode, where one payment
                          settles the bill.
                      warnings:
                        type: array
                        items:
                          type: string
                        description: >-
                          Non-fatal notes (a locked transaction that kept its
                          coding, an unset AP Clearing account, ...).
                    required:
                      - published
                      - provider
                      - billId
                      - updatedExisting
                      - payment
                      - paymentError
                      - warnings
                required:
                  - success
                  - data
        '400':
          description: >-
            Invoice not publishable, provider not connected, or provider
            validation 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
        '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 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
        '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:
    InvoiceProviderBody:
      type: object
      properties:
        provider:
          type: string
          enum:
            - xero
            - qbo
          description: >-
            Accounting provider. The company must be connected to it (GET
            /company: xeroLinked / qboLinked).
      required:
        - provider
    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.