QuickBooks Online

QuickBooks Online

This connector reads and writes one QuickBooks Online company through the QuickBooks Online Accounting API v3 (https://quickbooks.api.intuit.com/v3/company/<realm id>): company info, a read-only query language over every accounting entity (customers, vendors, items, accounts, invoices, bills, payments...), single records by Id, Profit and Loss, Balance Sheet and aged receivables and payables, and creating customers and invoices. It runs as the QuickBooks user who authorized the connector, on the company chosen at sign-in.

Setup (one-time, about 15 minutes)

1. Sign in at https://developer.intuit.com → My Hub → App dashboard → Create an app → QuickBooks Online and Payments, and select the scope com.intuit.quickbooks.accounting.
2. Under Settings → Redirect URIs add https://cloud.anythingmcp.com/api/mcp-oauth/callback on AnythingMCP Cloud, or <your AnythingMCP URL>/api/mcp-oauth/callback when you host AnythingMCP yourself, for Development and, later, Production. It must match exactly.
3. Copy the Client ID and Client Secret from Keys & credentials. Development keys work only with sandbox companies; production keys need Intuit's app assessment (questionnaire on the app dashboard) and work with real companies.
4. Find the company's realm id (Company ID): in QuickBooks, gear icon → Account and settings → Billing & subscription (Company ID, without spaces); for a sandbox company, on the developer site under Sandboxes. Paste it into QBO_REALM_ID.
5. Set QBO_API_URL to https://quickbooks.api.intuit.com for real companies or https://sandbox-quickbooks.api.intuit.com for a sandbox company. It must match the keys: development keys with the sandbox URL, production keys with the production URL.
6. Install, then on the connector page click Authorize with Provider, sign in to Intuit and connect the same company. AnythingMCP exchanges the code with HTTP Basic client authentication and stores the tokens encrypted.
7. Run qbo_get_company_info and check the company name before reading or writing anything. One connector reads one company; install another for a second company.

Tokens: access tokens last one hour and are renewed automatically. Intuit replaces the refresh token about every 24 hours and AnythingMCP stores each new one; a refresh token not used for 100 days expires, and every refresh token expires 5 years after the first authorization at the latest. After that, or after the app is disconnected in QuickBooks, click Authorize with Provider again. Do not use the same Intuit app's refresh token in another tool at the same time: one of the two will hold a replaced token.

Scope: com.intuit.quickbooks.accounting gives read and write access to the accounting data, as far as the signing-in user's QuickBooks role allows. Intuit has no read-only accounting scope: for a read-only setup, sign in with a QuickBooks user whose role cannot create transactions, and disable qbo_create_customer, qbo_update_customer, qbo_create_invoice.

Switched off at install: qbo_send_invoice (it emails the customer in the company's name) and qbo_delete_invoice. Turn them on per tool if the AI should send or delete invoices.

Creating records: qbo_create_invoice books a real invoice at once: QuickBooks has no drafts, it raises the customer's balance and appears in reports, but nothing is emailed. Look up the customer and the items with qbo_query first; each sales line needs Amount and SalesItemLineDetail.ItemRef.value (an Item Id). Companies with sales tax may also need TxnTaxDetail or a TaxCodeRef per line (non-US companies especially). Customers cannot be deleted, only made inactive with qbo_update_customer (active: false). Updates need the record's current SyncToken; read the record again if QuickBooks answers error 5010 (stale object).

Query language (qbo_query): SELECT * | fields | COUNT(*) FROM <Entity> [WHERE ...] [ORDERBY <field> [ASC|DESC]] [STARTPOSITION n] [MAXRESULTS n].

• One entity per query, no joins, no OR, no GROUP BY; combine conditions with AND. Operators =, <, >, <=, >=, IN ('1','2'), LIKE '%Acme%' (only %, only on name fields).
• Strings and dates in single quotes: TxnDate >= '2026-01-01', DisplayName = 'Acme GmbH'; a quote inside a string as \'. Booleans unquoted: Active = true.
• Only filterable fields can be used in WHERE, e.g. Id, DisplayName, Active, Balance, TxnDate, DueDate, DocNumber, CustomerRef, VendorRef, MetaData.LastUpdatedTime. Inactive customers, vendors and items are left out unless the query says Active IN (true, false).
• Results come in QueryResponse.<Entity>; STARTPOSITION is 1-based and MAXRESULTS goes up to 1000 (default 100). Page by raising STARTPOSITION by MAXRESULTS until fewer rows come back. COUNT(*) returns totalCount.
• Examples: open invoices select * from Invoice where Balance > '0' orderby DueDate; a customer's invoices select * from Invoice where CustomerRef = '58'; changed since select * from Customer where MetaData.LastUpdatedTime > '2026-10-01T00:00:00Z'.

Reports: qbo_report_profit_and_loss and qbo_report_balance_sheet take start_date/end_date (YYYY-MM-DD) or a date_macro such as "This Fiscal Year", optionally accounting_method (Accrual or Cash) and summarize_column_by (Month, Quarter...). The aged receivables and payables reports take a report_date. Report JSON has Header, Columns and nested Rows whose ColData values are strings.

Minor version: every call sends minorversion=75, the lowest version Intuit still serves since August 2025.

Rate limits: 500 requests per minute and 10 concurrent requests per company; over the limit Intuit answers 429. Prefer one query with MAXRESULTS 1000 over many small ones.

Common errors

• 401 AuthenticationFailed / 3200: the authorization expired or was revoked, or QBO_API_URL does not match the keys (sandbox keys against production or the other way round). Check the URL, then click Authorize with Provider again.
• 403 / 3100 ApplicationAuthorizationFailed: the realm id belongs to a company this authorization was not granted for, or the user's role lacks access. Check QBO_REALM_ID against the company connected at sign-in.
• 400 QueryParserError / QueryValidationError: query syntax (quotes, an unsupported operator such as OR, a field that cannot be filtered).
• 400 ValidationFault 6240 Duplicate Name Exists Error: the DisplayName is taken; 2040 Invalid String: a name contains a colon (it separates sub-customers), tab or line break; 610 Object Not Found: an Id that does not exist; 5010 Stale Object Error: read the record again for its SyncToken; 6000 business validation (for example a missing tax code).
• 429 ThrottleExceeded: wait a minute and retry.

Out of scope here: invoice PDFs and attachments, payments and bank feeds, payroll, QuickBooks Desktop, batch and change-data-capture calls, deleting anything except invoices.