Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The QuickBooks Online integration lets your agents query the accounting data in your QBO company file — customers, vendors, invoices, bills, payments, and the chart of accounts — and run financial reports like Profit & Loss, Balance Sheet, Cash Flow, and AR/AP aging. The connection is org-level: any agent in your workspace can use the QuickBooks tools once an admin has connected the integration. Unlike most other integrations in Aster, QuickBooks uses a one-click OAuth flow — admins click Connect, authorize via Intuit, and they’re done. No API keys to copy or refresh tokens to manage.

​
Features

  • One-click OAuth setup — click Connect, authorize via Intuit, done. No API keys to manage.
  • Query language — run QBO SELECT statements with automatic pagination across thousands of records.
  • Schema discovery — agents learn QuickBooks entities and field names at runtime via quickbooks_get_schema.
  • Financial reports — pull P&L, Balance Sheet, AR aging, AP aging, Customer/Vendor balances, Item Sales, Trial Balance, General Ledger, and ~25 other QBO reports with date macros (This Fiscal Year-to-date, Last Quarter, etc.).
  • Automatic token refresh — access tokens expire every 60 minutes; we refresh them transparently with no agent involvement.
  • Connection management modal — see when the integration was connected, view the QuickBooks Company ID, and track when authorization expires.

​
Prerequisites

  • A QuickBooks Online subscription (any tier — Simple Start, Essentials, Plus, or Advanced).
  • An Aster organization admin role to set up the integration. Once connected, every member of the org can use it through their agents.
  • The Intuit account used to authorize the connection must have access to the QuickBooks company you want to expose.

​
Setup Guide

1

Open Control Hub > Integrations

In Aster Agents, navigate to Control Hub > Integrations and locate the QuickBooks Online card.
2

Click Connect

Click Connect on the QuickBooks card. A modal will appear explaining the OAuth flow. Click Continue to QuickBooks Online to be redirected to Intuit.
3

Sign in to Intuit

Sign in with the Intuit account that has access to the QuickBooks company you want to connect. The QBO company you select on the Intuit consent screen is the one Aster will read from — make sure you pick the right one if you have access to multiple.
4

Authorize Aster

Approve the authorization request. Intuit will redirect you back to Aster, where you’ll see a “QuickBooks connected successfully” confirmation toast and the integration card will flip to Connected.
5

Add Tools to Your Agent

Edit any agent and enable the QuickBooks tools you want it to have:
  • QuickBooks Get Schema — discover entity and field names
  • QuickBooks Query — run SELECT queries against QBO entities
  • QuickBooks Get Report — run financial reports (P&L, Balance Sheet, etc.)
We recommend enabling all three — agents typically use Get Schema to learn the data model, then Query or Get Report to retrieve the data.

​
Available Tools

​
QuickBooks Query

Run QBO query language SELECT statements against any entity. Auto-paginates up to 10 pages × 1000 rows; pass auto_paginate: false if you’ve added your own STARTPOSITION / MAXRESULTS. 
SELECT Id, DisplayName, Balance
FROM Customer
WHERE Active = true
ORDER BY Balance DESC

SELECT Id, DocNumber, TxnDate, TotalAmt, CustomerRef
FROM Invoice
WHERE TxnDate >= '2026-01-01'
ORDER BY TxnDate DESC

SELECT COUNT(*) FROM Bill WHERE Balance > 0
QBO query language is similar to SQL but does not support JOINs, GROUP BY, or arbitrary aggregates — COUNT(*) is the only aggregate. Most analytical queries should be done by pulling the rows and aggregating client-side, or by using QuickBooks Get Report for built-in financial reports.

​
QuickBooks Get Schema

Discover available entities and their fields. Call without arguments to list every supported entity, or pass an entity name to get the field list and example queries. Currently surfaces these entities: Customer, Vendor, Invoice, Bill, Payment, BillPayment, Account, Item, Estimate, PurchaseOrder, Class, Department, CompanyInfo. For entities not in the curated list (e.g. JournalEntry, CreditMemo, Deposit, Transfer), you can still query them directly via quickbooks_query — see the Intuit API reference for the full list.

​
QuickBooks Get Report

Run any of QuickBooks’ built-in financial reports. Each returns a structured rows-and-columns response. Supported reports include:
  • P&L: ProfitAndLoss, ProfitAndLossDetail
  • Balance Sheet: BalanceSheet, BalanceSheetDetail
  • Cash flow: CashFlow
  • GL / Trial balance: TrialBalance, GeneralLedger, JournalReport
  • AR / AP aging: AgedReceivables, AgedReceivableDetail, AgedPayables, AgedPayableDetail
  • Customer / Vendor: CustomerSales, CustomerIncome, CustomerBalance, CustomerBalanceDetail, VendorBalance, VendorBalanceDetail, VendorExpenses
  • Inventory / Sales: ItemSales, InventoryValuationSummary
  • Other: TransactionList, TaxSummary, DepartmentSales, ClassSales
Date ranges can be specified with start_date + end_date (YYYY-MM-DD) or with date_macro:
  • Today, This Week, This Month, This Quarter, This Fiscal Year, This Fiscal Year-to-date
  • Yesterday, Last Week, Last Month, Last Quarter, Last Fiscal Year
Optional filters: accounting_method (Cash or Accrual), summarize_column_by (Total, Month, Quarter, Year, Customers, Vendors, Classes, Departments), and IDs for customer, vendor, class, department.

​
Managing Your Connection

Click the QuickBooks card again any time after connecting to open the management modal. From there you can:
  • See the connected Company ID (Intuit’s realmId)
  • See when the connection was created and how long until your authorization expires
  • Reconnect — refresh the OAuth grant (useful if you want to switch QBO companies, or your refresh token is approaching expiry)
  • Disconnect — revoke Aster’s access to your QuickBooks company

​
Token Lifecycle

  • Access tokens are valid for 60 minutes. Aster refreshes them automatically when they expire — no action required from you.
  • Refresh tokens are valid for ~100 days from the time the connection was created. As long as at least one agent uses the integration within that window, the refresh process renews the lifetime. If a connected QuickBooks integration sits unused for 100+ days, you’ll need to click Reconnect to re-authorize.
The management modal shows a warning when the refresh token is within 14 days of expiring.

​
Permissions and Scope

Aster requests the com.intuit.quickbooks.accounting scope when connecting, which is QuickBooks’ standard accounting scope. Intuit does not offer a read-only variant of this scope, so the consent screen will tell you Aster can read and write accounting data — however, the tools we ship today are read-only. We do not currently offer create/update/delete tools for QuickBooks records. If you need write access for a specific workflow, contact us.

​
Security Considerations

  • Admin-only setup: only organization admins can connect, reconnect, or disconnect QuickBooks. Regular members can use the tools through agents but cannot change the connection.
  • Tokens are stored at the org level in the connections JSONB on the organization_data table. They never leave the server in API responses (the API redacts them as [REDACTED]).
  • OAuth state is HMAC-signed with a dedicated OAUTH_STATE_SECRET to prevent CSRF and replay attacks during the consent flow.
  • Use a dedicated QBO user account (not the company owner) if you want to scope agent access. QuickBooks role-based permissions on the connecting user apply to everything Aster can read or write.
  • Revoke access at Intuit if you ever need to forcibly disconnect Aster from outside Aster: sign in to QuickBooks Online, go to Settings > Manage your Intuit Account > Apps, and remove the Aster Agents app.

​
Troubleshooting

The signed state token has expired (10-minute TTL). Click Connect again — this typically happens if you opened the consent screen, walked away, and came back later. The flow has to complete in one sitting.
Intuit refused to exchange the authorization code for tokens. The most common causes are:
  • Wrong redirect URI registered in the Intuit Developer app — verify your prod redirect URI exactly matches the one Aster sends (https://www.asteragents.com/api/integrations/quickbooks/callback).
  • Aster Intuit app credentials are misconfigured in Vercel environment (QBO_CLIENT_ID, QBO_CLIENT_SECRET). Contact your Aster admin if this persists.
The entity name in your query is wrong. Use QuickBooks Get Schema to see the supported entity list, or check the Intuit API reference for entities not in our curated catalog.
QBO query language is case-sensitive for entity and field names — SELECT * FROM customer returns nothing, but SELECT * FROM Customer works. Field names also must match exactly (e.g. DisplayName, not displayname or display_name).Also note that some QBO companies record income via Sales Receipts or Deposits rather than Invoices. If SELECT * FROM Invoice returns empty but the P&L shows revenue, try SELECT * FROM SalesReceipt instead.
QuickBooks refresh tokens expire after 100 days of disuse. Click Reconnect in the management modal and re-authorize via Intuit. Existing agents will start working again immediately.
The QBO company you bind is determined by which company you select on the Intuit consent screen. Click Reconnect in the management modal and pick a different company on the Intuit page.