QuickBooks

QuickBooks Online

All data is scoped to a Company (realm). realm_id is bound on the connection and applied automatically to every tool call.

Sandbox vs production API

Intuit exposes two accounting API hosts. The OAuth token and realm_id belong to one environment only. Use the credential Use QuickBooks sandbox API option for sandbox/developer companies; leave it off for live QuickBooks Online. Wrong host yields HTTP 403 / Intuit error 3100 (ApplicationAuthorizationFailed).

Key Entities

• Customer — buyers; linked to Invoices, Payments, Estimates, RefundReceipts
• Vendor — suppliers; linked to Bills, PurchaseOrders, BillPayments
• Invoice — sales documents (amounts owed by customers)
• Bill — purchase documents (amounts owed to vendors)
• Payment — customer payments applied to invoices
• Account — chart of accounts (assets, liabilities, equity, income, expenses)
• Item — products/services used on invoice/bill line items
• Employee — staff members for time tracking and payroll
• Estimate — quotes/proposals (can be sent to customers)
• PurchaseOrder — orders to vendors before receiving goods
• RefundReceipt — refunds given to customers

QBO Query (read path — not SQL)

Allowed entities (FROM target): Account, Attachable, Bill, BillPayment, Budget, Class, CompanyCurrency, CompanyInfo, CreditCardPayment, CreditMemo, Customer, CustomerType, Department, Deposit, Employee, Estimate, ExchangeRate, Invoice, Item, JournalCode, JournalEntry, Payment, PaymentMethod, Preferences, Purchase, PurchaseOrder, RefundReceipt, ReimburseCharge, SalesReceipt, TaxAgency, TaxClassification, TaxCode, TaxRate, Term, TimeActivity, Transfer, Vendor, VendorCredit. There is no generic Transaction, BankTransaction, Rule, or TransactionRule entity.

• Supported operators: =, !=, <, >, <=, >=, LIKE, IN. LIKE supports only the % wildcard (no _, no regex)
• OR is not supported at all — AND is the only way to join WHERE clauses. See the multi-value section below
• Booleans: Active = true / Active = false — not 0 / 1
• Operators must be literal: <, >, <=, >= in the query string — not HTML escapes (&lt;, &gt;, &lt;=, &gt;=)
• Dates: range filters on TxnDate — e.g. TxnDate >= '2026-01-01' AND TxnDate <= '2026-06-30'
• Amounts (TotalAmt, Balance): = or != with integer literals only — Balance = 0, not Balance > 0 or 304780.00
• Id: only = and IN — no <, >, !=, or LIKE
• Sort: ORDERBY Id or ORDERBY TxnDate (or MetaData.*); not DueDate, DisplayName, or TotalAmt
• Reference columns (VendorRef, CustomerRef, AccountRef, …) filter on the numeric Id, never the display name — a name returns Invalid ID (code 2030). Some entities do not expose the ref in WHERE at all (see EntityRef below)
• JournalEntry: no TotalAmt column — debits/credits live on Line[].Amount; use SELECT * or the report tool for balances
• Customer names: DisplayName, not Name; Purchase payee: filter EntityRef.value client-side after SELECT *, not VendorRef in WHERE
• Notes columns (PrivateNote, Memo) are selectable but not filterable — see reference-number search below
• No OR, JOIN, GROUP BY, SUM, AVG, MIN, MAX — use the report tool for monetary totals; page with MAXRESULTS for row sets
• Counting is supported: SELECT COUNT(*) FROM Invoice WHERE TxnDate >= '2026-01-01' returns {"totalCount": N}. It accepts WHERE, LIKE, and paging clauses, and is the right way to answer "how many" — do not page the whole entity to count it. COUNT(*) only: a column argument (COUNT(Id)) is a parse error

Matching several values (instead of OR): use IN on a single column and do it in one call — SELECT Id, DocNumber, TxnDate FROM Bill WHERE DocNumber IN ('1166542', '1166544', '1166547'). Never issue one query per value. When the values live in different columns, run one query per column and dedupe by Id — e.g. WHERE DisplayName LIKE '%Acme%' and WHERE CompanyName LIKE '%Acme%' as two calls.

Finding a transaction by reference number: if the number is the transaction's own document number, filter DocNumber IN (…). If it is written inside the memo, the Query API cannot reach it — run quickbooks_get_report with report_type='TransactionList', a date window, and columns='tx_date,txn_type,doc_num,name,memo,subt_nat_amount', then match your reference numbers against the memo column client-side. One report call covers an unlimited list of numbers.

Overdue invoices: page SELECT * FROM Invoice WHERE TxnDate >= '2024-01-01' MAXRESULTS 100, then filter DueDate and Balance client-side.

Entity directory (name → Id): after OAuth validation, Customer DisplayName/CompanyName, Vendor DisplayName, and Account Name/AcctNum are cached on the credential. Exact-name WHERE filters and simple LIKE '%name%' probes rewrite to WHERE Id = '…' before the API call — skip repeated LIKE scans when the name is already known. Pass refresh_directory=true on quickbooks_query after adding or renaming master data; responses include a directory envelope (counts + cache age).

Reports

The report tool allows up to 60 seconds per request. Wide date ranges (full-year General Ledger, multi-year P&L) can still time out — pass narrower start_date / end_date windows (month or quarter) and stitch results client-side instead of repeating the same wide range.

Report names are a fixed list and the spelling is exact: AccountList, AgedPayableDetail, AgedPayables, AgedReceivableDetail, AgedReceivables, BAS, BalanceSheet, CashFlow, ClassSales, CustomerBalance, CustomerBalanceDetail, CustomerIncome, CustomerSales, DepartmentSales, FECReport, GeneralLedger, GeneralLedgerFR, InventoryValuationDetail, InventoryValuationSummary, ItemSales, JournalReport, JournalReportFR, ProfitAndLoss, ProfitAndLossDetail, TaxSummary, TransactionList, TransactionListByCustomer, TransactionListByVendor, TransactionListWithSplits, TrialBalance, TrialBalanceFR, VendorBalance, VendorBalanceDetail, VendorExpenses.

The API names are not the report titles in the QuickBooks UI. This is the single biggest source of failed report calls, because the UI title looks like an obvious guess and every wrong guess returns the same permission error:

Report you want	API name
Sales by Customer	CustomerSales
Sales by Product/Service	ItemSales
Sales by Class	ClassSales
Sales by Department / Location	DepartmentSales
Income by Customer	CustomerIncome
Account List / Chart of Accounts	AccountList
A/R Aging Detail	AgedReceivableDetail (singular)
A/P Aging Summary	AgedPayables
Statement of Cash Flows	CashFlow

An unrecognized name comes back as Permission Denied Error (code 5020) rather than "not found", so a permission error on a report is usually a wrong name — not a missing role and not an expired connection. Check the name before re-authenticating; re-authenticating cannot fix it.

Payroll and budget reports do not exist in this API at any spelling (they are QuickBooks Desktop reports). Read payroll expense accounts through ProfitAndLoss or GeneralLedger instead. These are country-edition reports that only a France or Australia company can run: BAS, FECReport, GeneralLedgerFR, JournalReportFR, TaxSummary, TrialBalanceFR.

Transaction-level filters (doc_number, memo, transaction_type, name, columns, sorting, max_rows) only apply to the TransactionList family: TransactionList, TransactionListByCustomer, TransactionListByVendor, TransactionListWithSplits. Summary reports ignore them.

Reports cannot be paged. Unlike the Query path there is no row offset — a report returns its entire result set for the window you asked for. max_rows caps the rows from the top of the sort order, so it samples or gives a "top N" with sort_by; it cannot reach the rows past the cap. To cover a long period, walk it in date windows and stitch client-side.

TransactionList is also the cross-entity view for questions the Query API cannot answer in one pass — bank-feed activity, transactions by memo, or purchase-order status. Pick the columns you need with columns (for example tx_date,txn_type,doc_num,name,memo,po_status,subt_nat_amount); requesting every column makes the report markedly slower. memo and doc_number filter on an exact value, so for substring or list matching read the column back and match client-side.

Standard outputs include ProfitAndLoss, BalanceSheet, CashFlow, AgedReceivables, AgedPayables, GeneralLedger, TrialBalance, and more.

Upsert Pattern

All write tools use the upsert pattern:

• Create: Omit id and sync_token — returns the new entity with its QuickBooks ID
• Update: Provide id plus a fresh sync_token from a read of the same entity—QuickBooks rejects stale optimistic concurrency tokens.
• Customers/Vendors/Employees cannot be deleted — set active=false instead
• Transactions can be voided (preferred for audit trail) or deleted

Items and inventory

Item type is constrained by company settings and is close to immutable once set:

• Creating an Inventory item requires Track quantity on hand to be enabled in the company's sales settings. With it off, QuickBooks rejects the create (business validation error 6000) — create the item as NonInventory or Service, or ask the user to enable inventory tracking in QuickBooks first. This is a company setting; no API call can turn it on.
• An existing Inventory item cannot be converted to NonInventory or Service (error 2120). The reverse — NonInventory to Inventory — is allowed when inventory tracking is on. To reclassify an inventory item, deactivate it and create a replacement.
• Inventory items need asset_account_id, income_account_id, and expense_account_id; non-inventory items only need income and expense accounts.

Advanced features

• Batch: Run up to 30 operations in one round trip (writes and queries); queries inside batch obey the same QBO Query rules above
• CDC: List everything changed since a watermark timestamp
• PDF: Materialize base64 PDFs for invoices and estimates
• Attachments: Upload files linked to any supported entity
• Void: Reverse financial impact without deleting the source transaction

Common workflows

1. Find overdue invoices: Page invoices by TxnDate, filter DueDate and Balance client-side (see QBO Query section)
2. Create and send invoice: Create customer → create invoice → send invoice
3. Record payment: Find invoice ID → create payment linked to invoice
4. Expense tracking: Create vendor → create bill → pay bill from bank account
5. Procurement: Create PO → receive goods → convert to bill → pay bill
6. Refund: Create refund receipt linked to customer
7. Bulk import: Use batch tool to create up to 30 entities at once
8. Sync changes: Use CDC to detect all entities modified since last sync