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

# List Invoices API

> List the received invoices of a Breezing company with status, payment, and vendor filters, matching the invoice inbox in the dashboard.



## OpenAPI

````yaml GET /invoices
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:
    get:
      tags:
        - Invoices
      summary: List received invoices
      description: >-
        List the company's received (purchase) invoices with offset pagination
        and the same filters the dashboard inbox offers.


        Received invoices are vendor documents uploaded to Breezing and scanned
        by OCR. Lifecycle: processing (scan running) → review (a human checks
        the extracted fields) → approved (the books event: the invoice books a
        native accrual journal Dr expense / Cr accounts payable at the invoice
        date, and matched payments settle: they are coded to the Accounts
        Payable account, or to the AP clearing account when the company has
        one). "failed" scans are completed by hand and approved, or rescanned.


        Each row carries derived flags: inBooks/booksReasons (journal
        eligibility) and paymentStatus (paid/partial/unpaid/overdue, approved
        rows only). previewUrl is a short-lived signed link to the original
        document; storage paths are never exposed.
      parameters:
        - 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
        - schema:
            type: string
            enum:
              - processing
              - review
              - approved
              - failed
              - all
            description: >-
              Lifecycle filter. Default "all". "review" is the human inbox;
              "approved" the booked set.
          required: false
          description: >-
            Lifecycle filter. Default "all". "review" is the human inbox;
            "approved" the booked set.
          name: status
          in: query
        - schema:
            type: string
            enum:
              - published
              - unpublished
              - all
            description: >-
              published = a bill exists at ANY provider (Xero/QuickBooks/Bexio);
              unpublished = still needs publishing. Default "all".
          required: false
          description: >-
            published = a bill exists at ANY provider (Xero/QuickBooks/Bexio);
            unpublished = still needs publishing. Default "all".
          name: published
          in: query
        - schema:
            type: string
            enum:
              - inBooks
              - notInBooks
              - all
            description: >-
              inBooks = approved AND journal-eligible; notInBooks = approved but
              missing something the books need. Default "all".
          required: false
          description: >-
            inBooks = approved AND journal-eligible; notInBooks = approved but
            missing something the books need. Default "all".
          name: books
          in: query
        - schema:
            type: string
            enum:
              - paid
              - partial
              - unpaid
              - overdue
              - all
            description: >-
              Approved invoices only: paid, partial (allocated payments below
              the total), unpaid, or overdue (unpaid past the due date). Default
              "all".
          required: false
          description: >-
            Approved invoices only: paid, partial (allocated payments below the
            total), unpaid, or overdue (unpaid past the due date). Default
            "all".
          name: payment
          in: query
        - schema:
            type: string
            description: Narrow to invoices resolved to this vendor entity contact.
          required: false
          description: Narrow to invoices resolved to this vendor entity contact.
          name: vendorContactId
          in: query
        - schema:
            type: string
            maxLength: 200
            description: Substring match over vendor name, invoice number, file name.
          required: false
          description: Substring match over vendor name, invoice number, file name.
          name: search
          in: query
        - schema:
            type: string
            default: '50'
            description: Rows per page (1-200, default 50).
          required: false
          description: Rows per page (1-200, default 50).
          name: limit
          in: query
        - schema:
            type: string
            default: '0'
            description: Rows to skip (offset pagination, default 0).
          required: false
          description: Rows to skip (offset pagination, default 0).
          name: offset
          in: query
        - schema:
            type: string
            enum:
              - createdAt
              - vendorName
              - invoiceNumber
              - invoiceDate
              - dueDate
              - totalAmount
              - status
              - account
              - vat
            description: >-
              Sort column (default createdAt). account / vat sort by the GL
              coding, the table's inline columns.
          required: false
          description: >-
            Sort column (default createdAt). account / vat sort by the GL
            coding, the table's inline columns.
          name: orderBy
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: Sort direction (default desc).
          required: false
          description: Sort direction (default desc).
          name: sorting
          in: query
      responses:
        '200':
          description: Invoices retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
                      total:
                        type: integer
                        description: Total rows matching the filters.
                      hasMore:
                        type: boolean
                    required:
                      - limit
                      - offset
                      - total
                      - hasMore
                required:
                  - success
                  - data
                  - pagination
        '400':
          description: Invalid query parameters
          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
        '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:
    Invoice:
      type: object
      properties:
        id:
          type: number
        status:
          type: string
          enum:
            - processing
            - review
            - approved
            - failed
          description: >-
            processing = the Scan is running, review = extracted and waiting for
            a human, approved = in the books (immutable on journal fields),
            failed = the Scan failed (fill in manually and approve, or rescan).
        documentType:
          type: string
          nullable: true
          description: invoice | receipt | credit_note | other (from the scan).
        name:
          type: string
          description: Original file name.
        extension:
          type: string
        contentType:
          type: string
        pageCount:
          type: number
          nullable: true
        vendorName:
          type: string
          nullable: true
        vendorVatId:
          type: string
          nullable: true
        vendorIban:
          type: string
          nullable: true
        vendorContactId:
          type: number
          nullable: true
          description: >-
            The vendor entity contact resolved at approval (see the contacts
            isEntity flag), null before approval or when ambiguous.
        invoiceNumber:
          type: string
          nullable: true
        invoiceDate:
          type: string
          nullable: true
          description: Calendar day as yyyy-MM-dd (UTC), null when unknown.
          example: '2026-03-14'
        dueDate:
          type: string
          nullable: true
          description: Calendar day as yyyy-MM-dd (UTC), null when unknown.
          example: '2026-03-14'
        glImpactDate:
          type: string
          nullable: true
          description: >-
            Optional GL posting day override. The native accrual journal posts
            at glImpactDate, else invoiceDate.
          example: '2026-03-14'
        currency:
          type: string
          nullable: true
        totalAmount:
          type: string
          nullable: true
          description: Decimal string in the invoice currency, null when unknown.
        netAmount:
          type: string
          nullable: true
          description: Decimal string in the invoice currency, null when unknown.
        vatAmount:
          type: string
          nullable: true
          description: Decimal string in the invoice currency, null when unknown.
        totalAmountFiat:
          type: string
          nullable: true
          description: >-
            Company-currency total stamped at approval (the amount every report
            reads). Null before approval.
        netAmountFiat:
          type: string
          nullable: true
          description: Decimal string in the invoice currency, null when unknown.
        vatAmountFiat:
          type: string
          nullable: true
          description: Decimal string in the invoice currency, null when unknown.
        exchangeRate:
          nullable: true
          description: >-
            FX audit artifact stamped at approval: { base, target, rate, date,
            source: "same" | "manual" | "fxratesapi" }. Before approval a manual
            rate set via PATCH shows as { rate, source: "manual" }.
        account:
          type: string
          nullable: true
          description: GL account code (chart of accounts code) the expense books to.
        vat:
          type: string
          nullable: true
          description: >-
            Tax rate NAME from the company tax rate catalog (GET /taxes), or
            "no-vat".
        note:
          type: string
          nullable: true
        scanError:
          type: string
          nullable: true
        isPossibleDuplicate:
          type: boolean
        duplicateOfId:
          type: number
          nullable: true
        multiInvoiceSuspected:
          type: boolean
        reviewedBy:
          type: number
          nullable: true
        reviewedAt:
          type: number
          nullable: true
          description: unix ms
        xeroBillId:
          type: string
          nullable: true
        xeroPaymentId:
          type: string
          nullable: true
        qboBillId:
          type: string
          nullable: true
        qboPaymentId:
          type: string
          nullable: true
        bexioBillId:
          type: string
          nullable: true
        bexioPaymentId:
          type: string
          nullable: true
        publishedAt:
          type: number
          nullable: true
          description: unix ms
        inBooks:
          type: boolean
          description: >-
            True when the invoice is approved AND eligible for the native
            accrual journal (bookable document type, invoice date, currency,
            positive total, GL account, stamped fiat total).
        booksReasons:
          type: array
          items:
            type: string
          description: Why an APPROVED invoice is not in the books (empty otherwise).
        paymentStatus:
          type: string
          nullable: true
          enum:
            - paid
            - partial
            - unpaid
            - overdue
            - null
          description: >-
            Approved invoices only. Direct settlement: paid = the allocations of
            the matched transactions apply the invoice total within 1%, partial
            = they apply less, and a linked transaction that was not applied
            pays nothing. Clearing mode (the invoice was settled through the AP
            clearing account): paid = a matched transaction exists. A provider
            payment also means paid. Otherwise overdue = unpaid past the due
            date, else unpaid. Null before approval.
        previewUrl:
          type: string
          nullable: true
          description: >-
            Short-lived signed URL (about 10 minutes) to read the original
            document. Mint a fresh one by re-reading the invoice.
        createdAt:
          type: number
          description: unix ms
        updatedAt:
          type: number
          description: unix ms
      required:
        - id
        - status
        - documentType
        - name
        - extension
        - contentType
        - pageCount
        - vendorName
        - vendorVatId
        - vendorIban
        - vendorContactId
        - invoiceNumber
        - invoiceDate
        - dueDate
        - glImpactDate
        - currency
        - totalAmount
        - netAmount
        - vatAmount
        - totalAmountFiat
        - netAmountFiat
        - vatAmountFiat
        - account
        - vat
        - note
        - scanError
        - isPossibleDuplicate
        - duplicateOfId
        - multiInvoiceSuspected
        - reviewedBy
        - reviewedAt
        - xeroBillId
        - xeroPaymentId
        - qboBillId
        - qboPaymentId
        - bexioBillId
        - bexioPaymentId
        - publishedAt
        - inBooks
        - booksReasons
        - paymentStatus
        - previewUrl
        - createdAt
        - updatedAt

````

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