QuickBooks Online connector: answers from the books, invoices only after sign-off

This page is for the bookkeeper, controller or IT lead connecting a QuickBooks Online company to OrgRelay. It explains the five tools, the Intuit developer app you need, how the OAuth tokens stay alive, and what an approver should check before an invoice goes into the ledger.

#What staff can ask

QuickBooks questions usually come from sales and operations staff who don't have a QuickBooks seat. They tend to look like this:

• "What did we bill Harbor Supplies in October?" calls customers.search to find the customer ID, then finance.invoices with customer_id, date_from: 2026-10-01 and date_to: 2026-10-31.
• "Which invoices are more than 30 days late?" calls finance.receivables with overdue_only: true. The answer lists days_overdue per invoice, so the AI can sort out the 30-plus ones.
• "How did Q3 profit compare with Q2?" calls finance.summary twice, once per quarter, and compares the totals.
• "Invoice Harbor Supplies for 12 hours of installation at 85." calls finance.create_invoice. Nothing is posted until someone approves it.

#Tools

The read tools use the QuickBooks query language with STARTPOSITION and MAXRESULTS. limit defaults to 20 and is capped at 100, and the cursor is the next start position. Results follow the field names in the connector spec. Invoice results include email_status, which tells the AI whether QuickBooks has already sent the invoice. One detail matters for finance.receivables: overdue_only filters after the page is fetched, so a page can contain fewer rows than limit while more pages still exist. The tool names come from the shared standard tools list, so the same prompts work against Xero and Odoo.

Every request adds minorversion=75. Intuit made 75 the base minor version in 2025, so older minor versions no longer apply.

#Credentials and scopes

QuickBooks Online uses OAuth 2.0 authorization code flow, so you register your own app with Intuit. The form fields are:

• Client ID and Client secret from your app's Keys & credentials page. Development keys work only against sandbox companies. Production keys work against real companies.
• Company ID (Realm ID), required. In QuickBooks it is under the gear menu at Account and settings → Billing & subscription.
• Environment: leave empty or production for live companies, or enter sandbox. Any value containing "sand", "test" or "dev" switches the API host to sandbox-quickbooks.api.intuit.com.
• Advanced, normally untouched: the API base URL and the OAuth base URL.

The connector requests a single scope, com.intuit.quickbooks.accounting. Intuit does not offer a read-only accounting scope, so the consent screen grants accounting read and write. Read-only use is enforced on the OrgRelay side by turning off finance.create_invoice.

Token handling follows Intuit's rules, and OrgRelay does the refreshing:

• Access tokens last one hour. OrgRelay refreshes shortly before expiry, using HTTP Basic client authentication against Intuit's token endpoint, and stores the new pair encrypted, as described in the security model.
• Intuit's authorization FAQ describes refresh tokens as valid for 100 days on a rolling basis, extended each time they are used. Since September 2025 every refresh token also has a five-year maximum. When the five-year cap is reached, or after 100 days with no use at all, open the connection in OrgRelay and click Re-authorize.
• Intuit can return a new refresh token value on refresh. OrgRelay always keeps the latest one, which is why you should not reuse the same app credentials in a second tool that refreshes independently against the same company.

#Which actions need approval and what the approver sees

Only finance.create_invoice writes, and it always becomes an approval request. The reasoning behind asking first is on the human-in-the-loop page. The approver sees the customer ID, every line (description, quantity, unit price, item ID), the due date and the optional invoice number.

Things to check before approving:

• There is no draft. QuickBooks Online creates the invoice as a real transaction. It shows up in A/R and in reports as soon as it is approved. To undo it, someone voids or deletes it in QuickBooks.
• Item ID. Each line needs a product or service. If item_id is left out, the connector uses ID 1, which in many companies is the default "Services" item. Its income account decides where revenue lands, so ask for the correct item when it matters.
• Line amount. The connector computes Amount as quantity times unit price, rounded to cents. Tax is applied by QuickBooks according to the company's sales tax settings.
• Invoice number. If doc_number is blank, numbering follows the company's own transaction-number settings.

After approval the result shows the new invoice number and confirms it was not sent. The approved call carries OrgRelay's key orgrelay-approval-<approval id>, which ties the invoice back to its approval in the audit log. Finance teams usually route this tool to the controller as the designated approver. The finance agent page shows that set-up.

#Set it up

1. Sign in at developer.intuit.com and create an app for QuickBooks Online and Payments. Select the com.intuit.quickbooks.accounting scope and name it OrgRelay.
2. Under Keys & credentials, add the redirect URI that OrgRelay displays: your OrgRelay address plus /oauth/callback. For sandbox keys, http://localhost style addresses are accepted. For production keys, the callback must be a publicly reachable HTTPS address: no localhost, no private IP, no plain http. If OrgRelay is only reachable on the office network, set up external access with a domain first.
3. To use production keys, complete Intuit's app profile and questionnaire. Sandbox keys work right away, and every developer account includes a free sandbox company.
4. Find the Realm ID in QuickBooks under Account and settings → Billing & subscription.
5. In OrgRelay, open Admin → Business systems → App directory, choose QuickBooks Online, enter the client ID, secret, Realm ID and environment, and click Authorize. Sign in as a QuickBooks company admin and consent.
6. OrgRelay reads CompanyInfo and shows the company name, with "(sandbox)" for sandbox connections. Grant the connection to roles and review the authentication options if you manage several companies.

#Limits and things it deliberately does not do

• Intuit's throttles, from its limits page: 500 requests per minute per realm ID, and 10 requests per second per realm ID and app. When Intuit answers with HTTP 429, OrgRelay treats it as a rate limit rather than a failure. An approved invoice that hits the limit is queued and retried after the wait Intuit asks for, and a read reports the limit without counting toward OrgRelay's failure pause. OrgRelay's own ceiling is 120 calls per minute per connection, with a 60-second pause after three consecutive failures.
• One company per connection. Each Realm ID is a separate connection. Accounting firms add one connection per client company. Payment details from your processor come from a separate source such as the Stripe connector.
• Not exposed: bills, payments, journal entries, estimates, items, vendors, the balance sheet, sending invoices, voiding or deleting. Payroll is out of scope, because the accounting scope does not cover it.
• Report shape. finance.summary returns the summary line of each report section and subsection, such as Income, Cost of Goods Sold and Net Income, not every account row, which keeps answers within the roughly 12,000 characters the AI reads.
• Sandbox companies are free and reset-able, which makes them the right place for your first approval run.

#Official MCP server and OrgRelay

Intuit publishes an open-source QuickBooks Online MCP server on GitHub. It is written in TypeScript and configured with your app's client ID, secret, refresh token and Realm ID. It covers create, read, update, delete and search across 29 entity types plus 11 reports, with environment flags to suppress create, update or delete tools. Intuit describes it as a local server that runs as a stdio subprocess on a developer's machine.

That transport matters for OrgRelay. A third-party MCP connection in OrgRelay talks Streamable HTTP (see MCP transports) and authenticates with a bearer token or OAuth client credentials. A stdio server cannot be connected to OrgRelay directly, so the Intuit server is a tool for individual developers rather than for an OrgRelay connection. Inside OrgRelay, the connector on this page is the route to QuickBooks Online.

What OrgRelay adds through this connector is the company-level layer. Tools are granted per role, every write waits for an approver, calls share one audit log with your other systems, and everything runs on the company's own machine. If you would rather run the Intuit server for yourself inside an IDE, the Claude Code and Cursor guides show the client side. See official MCP servers for how OrgRelay treats vendor servers in general, and enterprise patterns for company-wide set-ups.

#Common questions

Is there a read-only scope for QuickBooks Online? No. The connector requests com.intuit.quickbooks.accounting, which Intuit grants as one accounting scope. Read-only behaviour comes from OrgRelay instead, by switching off finance.create_invoice for the connection or for specific roles.

Why does the connector ask for the Realm ID separately? Every Accounting API path includes the company ID, as in /v3/company/{realmId}/invoice. OrgRelay stores the Realm ID you enter and checks it during Connect by reading that company's CompanyInfo record.

Will customers receive an email when the AI creates an invoice? No. The connector sets EmailStatus to NotSet and never calls the send endpoint. The invoice does count toward accounts receivable immediately, because QuickBooks Online has no draft invoice state.

#Related

• All connectors
• Stripe connector for payment data next to invoices
• Human-in-the-loop approvals
• Connector check tool
• MCP overview
• Developer docs home