invoices query — account, payment state, status and type filters

Summary

The invoices query filters input now supports exact-match filters for finance exports and account-level synchronisation:

• accountId — invoices billed to that account (Invoice.accountId)
• paidOrOutstanding — InvoicePaidOrOutstanding enum (Paid, Outstanding, Void), matching Invoice.paidOrOutstanding
• status — InvoiceStatus enum (active, cancelled), matching Invoice.status
• type — InvoiceExtendedType enum (invoice, creditNote, paymentOnAccount), matching Invoice.type

These filters compose with existing dateRange, pagination, cursorPagination, options, and other filters fields using AND semantics. Omitting the new fields leaves existing invoices behaviour unchanged, including practice scoping and the seeInvoices permission.

Invoice.outstanding remains queryable on each result. It is not a filter (no range or numeric matching).

This release is additive.

Accepted values

Filter	GraphQL enum	Values
paidOrOutstanding	InvoicePaidOrOutstanding	Paid, Outstanding, Void
status	InvoiceStatus	active, cancelled
type	InvoiceExtendedType	invoice, creditNote, paymentOnAccount

paidOrOutstanding, status, and type are GraphQL enums (same names as the Invoice string values). Invalid enum values are rejected by GraphQL. Malformed accountId values return BAD_USER_INPUT.

Example

query OutstandingAccountInvoices($accountId: ID!) {
  invoices(
    dateRange: { start: "2026-01-01", end: "2026-12-31" }
    pagination: { page: 1, pageSize: 50 }
    filters: {
      accountId: $accountId
      paidOrOutstanding: Outstanding
      status: active
      type: invoice
    }
  ) {
    data {
      id
      invoiceNumber
      accountId
      status
      type
      paidOrOutstanding
      outstanding
    }
    pageInfo {
      hasMore
    }
  }
}

Integration guidance

• Combine filters when you need a narrow export (for example unpaid invoices for one billed account). Every supplied filter must match.
• Use paidOrOutstanding: Outstanding to retrieve invoices that still have a positive balance. Void matches cancelled invoices (status: cancelled).
• outstanding is the remaining amount on each invoice. Do not send it as a filter argument.
• Prefer cursorPagination for large date-range or account-level exports.

See also

• API reference: InvoicesQueryFilters
• API reference: Invoice