A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The QuickBooks API is how an app or AI agent works with a QuickBooks company's books: creating an invoice, recording a payment, adding a customer or vendor, and querying bills and accounts. Access is granted through an OAuth token tied to one connected company, and a single accounting permission grants that token full read and write access to every accounting record, with no per-record scope. A change to a record can emit an event that QuickBooks delivers to a registered endpoint.
How an app or AI agent connects to QuickBooks determines what it can reach. There is a route for making calls, a route for receiving events, and a first-party server that exposes QuickBooks tools to agents, and each is governed by the token behind it and the company it is connected to.
The Accounting API answers at https://quickbooks.api.intuit.com (and https://sandbox-quickbooks.api.intuit.com for sandbox), under /v3/company/{realmId}. The realmId identifies the connected QuickBooks company. A request takes and returns JSON, pins a numbered minor version with the minorversion query parameter, and runs reads either by id or through the shared /query endpoint.
QuickBooks POSTs an event notification to an HTTPS endpoint registered in the developer portal when records change in a connected company. The payload names the entity, the operation (Create, Update, Delete), and the company, but not the changed data, so an integration fetches the record afterward. An intuit-signature header, verified against the app's verifier token, confirms the request came from Intuit.
Intuit publishes a first-party Model Context Protocol server at github.com/intuit/quickbooks-online-mcp-server. It is an early preview that runs locally as a stdio subprocess, authenticates to a company with OAuth 2.0, and exposes QuickBooks entities and reports as callable tools, with environment variables to disable write, update, or delete tools.
QuickBooks uses the OAuth 2.0 authorization-code flow. A user connects a company and consents, and the app receives an access token plus a refresh token tied to that company's realmId. The access token is short-lived and refreshed with the refresh token. There is no per-entity scope: the accounting scope grants the token full read and write access to every accounting entity in the connected company.
On top of OAuth 2.0, QuickBooks supports OpenID Connect for signing a user in with their Intuit account. The openid, profile, email, phone, and address scopes return identity details about the user, separate from the accounting scope that grants data access.
The QuickBooks API is split into the accounting records an agent can act on, like customers, invoices, items, payments, bills, vendors, and accounts. Each is created, read, updated, and queried through its own methods, and a write changes the company's books.
Create, read, update, and query the customers a company invoices.
Create, read, update, delete, send, and query sales invoices.
Create, read, update, and query the products and services on a sale.
Create, read, update, delete, and query payments received against invoices.
Create, read, update, delete, and query bills owed to vendors.
Create, read, update, and query the vendors a company buys from.
Create, read, update, and query the chart-of-accounts ledgers.
Read company information and run SQL-like queries across entities.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
CustomersCreate, read, update, and query the customers a company invoices.4 | ||||||
| POST | /v3/company/{realmId}/customer | Create a customer. | write | accounting | Current | |
Granted by the single com.intuit.quickbooks.accounting scope, which covers all accounting entities; there is no per-entity scope. Acts onCustomer Permission (capability) accountingVersionAvailable since the API’s base version Webhook event customer.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/customer/{customerId} | Read a single customer by id. | read | accounting | Current | |
Granted by com.intuit.quickbooks.accounting; the same scope covers reads and writes. Acts onCustomer Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/company/{realmId}/customer | Update a customer, posting the full object with its current SyncToken (a sparse update is also supported). | write | accounting | Current | |
An update posts to the entity path, not an id path; the SyncToken must match the current version or the call is rejected. Acts onCustomer Permission (capability) accountingVersionAvailable since the API’s base version Webhook event customer.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/query | Query customers with a SQL-like statement, like select * from Customer. | read | accounting | Current | |
All queries run through the shared /query endpoint; the entity is named in the statement. Acts onCustomer Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InvoicesCreate, read, update, delete, send, and query sales invoices.6 | ||||||
| POST | /v3/company/{realmId}/invoice | Create an invoice. | write | accounting | Current | |
Granted by com.intuit.quickbooks.accounting. Acts onInvoice Permission (capability) accountingVersionAvailable since the API’s base version Webhook event invoice.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/invoice/{invoiceId} | Read a single invoice by id. | read | accounting | Current | |
Granted by com.intuit.quickbooks.accounting. Acts onInvoice Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/company/{realmId}/invoice | Update an invoice, posting the full object with its current SyncToken (a sparse update is also supported). | write | accounting | Current | |
A full update replaces the object; the SyncToken must match the current version. Acts onInvoice Permission (capability) accountingVersionAvailable since the API’s base version Webhook event invoice.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/company/{realmId}/invoice?operation=delete | Delete an invoice, posting its id and SyncToken with operation=delete. | write | accounting | Current | |
Transaction entities like invoices are deleted through a POST with operation=delete, not an HTTP DELETE. Acts onInvoice Permission (capability) accountingVersionAvailable since the API’s base version Webhook event invoice.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/company/{realmId}/invoice/{invoiceId}/send | Email an invoice as a PDF to the customer. | write | accounting | Current | |
Sends to the address on the invoice, or to a sendTo address passed as a query parameter. Acts onInvoice Permission (capability) accountingVersionAvailable since the API’s base version Webhook event invoice.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/query | Query invoices with a SQL-like statement, like select * from Invoice. | read | accounting | Current | |
Runs through the shared /query endpoint. Acts onInvoice Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ItemsCreate, read, update, and query the products and services on a sale.4 | ||||||
| POST | /v3/company/{realmId}/item | Create an item, a product or service that can appear on a sale. | write | accounting | Current | |
Granted by com.intuit.quickbooks.accounting. Acts onItem Permission (capability) accountingVersionAvailable since the API’s base version Webhook event item.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/item/{itemId} | Read a single item by id. | read | accounting | Current | |
Granted by com.intuit.quickbooks.accounting. Acts onItem Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/company/{realmId}/item | Update an item, posting the full object with its current SyncToken (a sparse update is also supported). | write | accounting | Current | |
The SyncToken must match the current version. Acts onItem Permission (capability) accountingVersionAvailable since the API’s base version Webhook event item.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/query | Query items with a SQL-like statement, like select * from Item. | read | accounting | Current | |
Runs through the shared /query endpoint. Acts onItem Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PaymentsCreate, read, update, delete, and query payments received against invoices.4 | ||||||
| POST | /v3/company/{realmId}/payment | Create a payment, recording money received and applying it to invoices. | write | accounting | Current | |
This is accounting data; recording a received payment differs from charging a card, which needs the separate com.intuit.quickbooks.payment scope. Acts onPayment Permission (capability) accountingVersionAvailable since the API’s base version Webhook event payment.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/payment/{paymentId} | Read a single payment by id. | read | accounting | Current | |
Granted by com.intuit.quickbooks.accounting. Acts onPayment Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/company/{realmId}/payment | Update a payment, posting the full object with its current SyncToken (a sparse update is also supported). | write | accounting | Current | |
The SyncToken must match the current version. Acts onPayment Permission (capability) accountingVersionAvailable since the API’s base version Webhook event payment.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/company/{realmId}/payment?operation=delete | Delete a payment, posting its id and SyncToken with operation=delete. | write | accounting | Current | |
Transaction entities are deleted through a POST with operation=delete. Acts onPayment Permission (capability) accountingVersionAvailable since the API’s base version Webhook event payment.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BillsCreate, read, update, delete, and query bills owed to vendors.4 | ||||||
| POST | /v3/company/{realmId}/bill | Create a bill, an amount owed to a vendor. | write | accounting | Current | |
Granted by com.intuit.quickbooks.accounting. Acts onBill Permission (capability) accountingVersionAvailable since the API’s base version Webhook event bill.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/bill/{billId} | Read a single bill by id. | read | accounting | Current | |
Granted by com.intuit.quickbooks.accounting. Acts onBill Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/company/{realmId}/bill | Update a bill, posting the full object with its current SyncToken (a sparse update is also supported). | write | accounting | Current | |
The SyncToken must match the current version. Acts onBill Permission (capability) accountingVersionAvailable since the API’s base version Webhook event bill.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/company/{realmId}/bill?operation=delete | Delete a bill, posting its id and SyncToken with operation=delete. | write | accounting | Current | |
Transaction entities are deleted through a POST with operation=delete. Acts onBill Permission (capability) accountingVersionAvailable since the API’s base version Webhook event bill.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
VendorsCreate, read, update, and query the vendors a company buys from.4 | ||||||
| POST | /v3/company/{realmId}/vendor | Create a vendor. | write | accounting | Current | |
Granted by com.intuit.quickbooks.accounting. Acts onVendor Permission (capability) accountingVersionAvailable since the API’s base version Webhook event vendor.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/vendor/{vendorId} | Read a single vendor by id. | read | accounting | Current | |
Granted by com.intuit.quickbooks.accounting. Acts onVendor Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/company/{realmId}/vendor | Update a vendor, posting the full object with its current SyncToken (a sparse update is also supported). | write | accounting | Current | |
The SyncToken must match the current version. Acts onVendor Permission (capability) accountingVersionAvailable since the API’s base version Webhook event vendor.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/query | Query vendors with a SQL-like statement, like select * from Vendor. | read | accounting | Current | |
Runs through the shared /query endpoint. Acts onVendor Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountsCreate, read, update, and query the chart-of-accounts ledgers.4 | ||||||
| POST | /v3/company/{realmId}/account | Create an account in the chart of accounts. | write | accounting | Current | |
Granted by com.intuit.quickbooks.accounting. Acts onAccount Permission (capability) accountingVersionAvailable since the API’s base version Webhook event account.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/account/{accountId} | Read a single account by id. | read | accounting | Current | |
Granted by com.intuit.quickbooks.accounting. Acts onAccount Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/company/{realmId}/account | Update an account, posting the full object with its current SyncToken (a sparse update is also supported). | write | accounting | Current | |
Accounts cannot be deleted through the API; they are made inactive with an update instead. Acts onAccount Permission (capability) accountingVersionAvailable since the API’s base version Webhook event account.changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/query | Query accounts with a SQL-like statement, like select * from Account. | read | accounting | Current | |
Runs through the shared /query endpoint. Acts onAccount Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Company & queryRead company information and run SQL-like queries across entities.2 | ||||||
| GET | /v3/company/{realmId}/companyinfo/{realmId} | Read the company's information, like its name, address, and fiscal-year settings. | read | accounting | Current | |
A common first call to confirm the connection and read company settings. Acts onCompanyInfo Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/company/{realmId}/query | Run a SQL-like query across any supported entity, with where, orderby, and maxresults clauses. | read | accounting | Current | |
One endpoint serves every entity; the query statement names the entity and returns at most 1,000 rows per page. Acts onQuery Permission (capability) accountingVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
QuickBooks can notify an app when a record changes in a connected company, like an invoice being created or a customer being updated. It sends an event that names the entity, the operation, and the company, so an integration fetches the changed record rather than polling.
| Event | What it signals | Triggered by |
|---|---|---|
Customer (Create, Update, Delete) | Fires when a customer is created, updated, or merged in a connected company. | /v3/company/{realmId}/customer/v3/company/{realmId}/customer |
Invoice (Create, Update, Delete) | Fires when an invoice is created, updated, sent, or deleted in a connected company. | /v3/company/{realmId}/invoice/v3/company/{realmId}/invoice/v3/company/{realmId}/invoice?operation=delete/v3/company/{realmId}/invoice/{invoiceId}/send |
Item (Create, Update, Delete) | Fires when an item, a product or service, is created or updated in a connected company. | /v3/company/{realmId}/item/v3/company/{realmId}/item |
Payment (Create, Update, Delete) | Fires when a payment is created, updated, or deleted in a connected company. | /v3/company/{realmId}/payment/v3/company/{realmId}/payment/v3/company/{realmId}/payment?operation=delete |
Bill (Create, Update, Delete) | Fires when a bill is created, updated, or deleted in a connected company. | /v3/company/{realmId}/bill/v3/company/{realmId}/bill/v3/company/{realmId}/bill?operation=delete |
Vendor (Create, Update, Delete) | Fires when a vendor is created or updated in a connected company. | /v3/company/{realmId}/vendor/v3/company/{realmId}/vendor |
Account (Create, Update, Delete) | Fires when an account in the chart of accounts is created or updated in a connected company. | /v3/company/{realmId}/account/v3/company/{realmId}/account |
QuickBooks limits how fast an app can call, by a request rate measured per minute for each connected company and by a separate limit on how many requests run at once.
QuickBooks throttles each connected company separately, identified by its realmId. The Accounting API allows up to 500 requests per minute per company, with at most 10 requests running at once for the app. The batch endpoint, which bundles several operations into one call, has its own lower per-minute limit. Going over returns HTTP 429, the point to back off and retry with exponential backoff and jitter.
Queries run through the shared /query endpoint and page with the STARTPOSITION and MAXRESULTS clauses in the query statement, where MAXRESULTS tops out at 1,000 rows per page. There are no cursors; an integration advances STARTPOSITION to walk through the results.
A single query returns at most 1,000 rows. The batch endpoint accepts at most 30 operations per request. An app should pin the API version with the minorversion query parameter so a later minor version does not change a response unexpectedly.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | ValidationFault | The request was understood but a value is invalid or a business rule failed, like a missing required field, an unsupported character, or a stale SyncToken. The Fault element carries an Error with a code, a Message, and a Detail. | Read the Error code and Detail, fix the named field, and resend. The request is not retryable as-is. |
| 401 | AuthenticationFault | The access token is missing, expired, or invalid. | Refresh the access token with the refresh token, or reconnect the company if the refresh token has expired. |
| 403 | AuthorizationFault | The token is valid but not allowed for this request, for example the connected company lacks the accounting scope, or the app lacks access to the feature. | Confirm the app requested the com.intuit.quickbooks.accounting scope and that the company was connected with it. |
| 429 | ThrottleExceeded | The per-minute request rate or the concurrent-request limit for the company was exceeded. | Back off and retry with exponential backoff and jitter, and reduce how many requests run at once. |
| 500 | SystemFault / ServiceFault | An unexpected error on Intuit's side, which can also appear as 503 when the service is temporarily unavailable. | Retry with backoff, and contact Intuit support if it persists. |
QuickBooks keeps one API version, version 3, and ships dated, numbered minor versions on top of it that an app pins with a query parameter on each request.
The QuickBooks Online Accounting API is version 3. Rather than minting new major versions, Intuit ships dated, numbered minor versions on top of v3 that add fields and behaviors, and an app pins one with the minorversion query parameter on each request. Leaving minorversion off now uses minor version 75, the default since older minor versions were retired.
Intuit applied a dedicated, lower per-minute throttle to the batch endpoint in the production environment, separate from the per-company request rate. Calls to the batch endpoint that exceed this limit return HTTP 429.
Intuit deprecated support for minor versions 1 through 74 of the Accounting API. From this date, requests that do not pin a newer minor version, or pin a deprecated one, default to minor version 75. Apps were asked to pin minorversion=75 and test against it.
Intuit announced upcoming changes to the Accounting API that could impact existing applications, including the move toward minor version 75 and the retirement of older minor versions, giving integrators time to migrate.
Pin a minor version and move up on a schedule that suits the integration.
QuickBooks API minor versions ↗Bollard AI sits between a team's AI agents and QuickBooks. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.