QuickBooks Online API Patterns

Overview

The QuickBooks Online (QBO) API is a RESTful JSON API that provides access to customers, invoices, payments, purchases, bills, vendors, accounts, items, estimates, credit memos, and financial reports. This skill covers OAuth2 authentication, the Intuit query language, pagination, error handling, and performance optimization patterns for MSP accounting workflows.

Anti-triggers

• Xero's request model — the other accounting platform here also uses

OAuth2 and also has a tenant/realm concept, but its query syntax, pagination, and concurrency control are entirely different. Use xero-api-patterns. QBO's SyncToken optimistic locking in particular has no Xero equivalent, so a pattern copied across will fail in a way that reads like a permissions error.

• **QuickBooks tools missing from the client entirely, or a 401 before any

call succeeds** — the OAuth grant lives at the gateway, not in client config; use shared-skills-wyre-gateway-troubleshooting.

• Which realm am I writing to — production and sandbox are selected by

the gateway connection, not by a parameter on the call. Verify before any write; the request shapes are identical either way.

Authentication

OAuth2 Flow

QuickBooks Online uses OAuth2 for authentication. All API requests require a valid Bearer token in the Authorization header:

GET /v3/company/1234567890/customer/1
Authorization: Bearer eyJlbmMiOiJBMTI4Q0JDLUhT...
Accept: application/json
Content-Type: application/json

Required Headers:

Base URL Pattern

All API endpoints follow the pattern:

https://{base}/v3/company/{realmId}/{resource}

Production:

https://quickbooks.api.intuit.com/v3/company/1234567890/invoice

Sandbox:

https://sandbox-quickbooks.api.intuit.com/v3/company/1234567890/invoice

The realmId (Company ID) is a unique numeric identifier for each QuickBooks company. It is required in every API URL.

Minor Version Header

QuickBooks Online uses a minorversion query parameter to control API behavior. Always specify the latest minor version to access current features:

GET /v3/company/1234567890/customer/1?minorversion=73
Authorization: Bearer {access_token}

If omitted, the API defaults to the earliest supported minor version, which may lack newer fields or features.

Token Lifecycle

See references/auth.md for environment variables, the token refresh implementation, and node-quickbooks SDK setup.

Intuit Query Language

QuickBooks Online uses a SQL-like query language for searching and filtering entities. Queries are sent via GET request to the /query endpoint, and the query parameter value must be URL-encoded.

Query Syntax

SELECT * FROM EntityName WHERE condition [AND condition] [ORDERBY field [ASC|DESC]] [STARTPOSITION n] [MAXRESULTS n]

GET /v3/company/{realmId}/query?query=SELECT * FROM Invoice WHERE CustomerRef = '123' AND Balance > '0'&minorversion=73

Note that numeric comparison values are quoted as strings (Balance > '0').

Query Operators

Query Pagination

Use STARTPOSITION and MAXRESULTS for pagination:

SELECT * FROM Customer STARTPOSITION 1 MAXRESULTS 100
SELECT * FROM Customer STARTPOSITION 101 MAXRESULTS 100
SELECT * FROM Customer STARTPOSITION 201 MAXRESULTS 100

See references/api.md for more query examples and a full pagination loop implementation.

CRUD Operations

Most entities support deactivation (set Active: false) instead of hard delete.

SyncToken (Optimistic Locking)

Every entity has a SyncToken field that must be included in update requests. This prevents concurrent modification conflicts:

{
  "Id": "123",
  "SyncToken": "2",
  "DisplayName": "Acme Corporation - Updated"
}

If the SyncToken does not match the current value on the server, the update returns a 5010 stale object error.

See references/api.md for the full request/response formats and complete CRUD examples.

Rate Limiting

When rate limited, QBO returns HTTP 429 with a THROTTLE fault (code 3001). Honor the Retry-After header and add jitter before retrying. See references/api.md for a retry implementation that also handles 401 token refresh.

Error Handling

QBO returns errors in a structured Fault object with a type (AuthenticationFault, AuthorizationFault, ValidationFault, THROTTLE) and an Error array carrying Message, Detail, and a numeric code. Route on Fault.type first, then the error code.

Most frequently hit codes:

See references/errors.md for the complete HTTP status table, Fault object samples, and an error dispatch implementation.

Webhooks

QuickBooks Online supports webhooks for real-time notifications when entities change. The payload carries a realmId plus a dataChangeEvent.entities array of { name, id, operation, lastUpdated }. Configure webhooks in the Intuit Developer Portal under your app's settings.

See references/api.md for a full webhook payload example.

Best Practices

1. Always include `minorversion` - Specify the latest version (73) in every request; omitting it silently falls back to the oldest supported version
2. Use the query endpoint - Batch lookups with queries instead of individual GETs
3. Include SyncToken on updates - Required for all update operations, or you get a 5010 stale object error
4. Use sparse updates - Without sparse: true, omitted fields are cleared
5. Encode query strings - URL-encode the query parameter value
6. Cache reference data - Items, accounts, and tax codes change infrequently
7. Monitor token expiry - Access tokens expire after 60 minutes; refresh proactively

Related Skills

• QBO Customers - Customer management
• QBO Invoices - Invoice management
• QBO Payments - Payment processing
• QBO Expenses - Expense tracking
• QBO Reports - Financial reporting