QuickBooks Online API Skill
This skill provides production-grade workflows, JSON schemas, and code patterns for integrating with the QuickBooks Online (QBO) REST API (v3) and the QuickBooks Payments API (v4).
Base URLs
| Environment | Accounting API Base URL |
|---|---|
| Sandbox | https://sandbox-quickbooks.api.intuit.com |
| Production | https://quickbooks.api.intuit.com |
All requests require the header Authorization: Bearer <access_token> and Accept: application/json.
Reference Guides
Detailed schemas and code implementations are in the references/ folder. Load them as needed:
| File | When to Read |
|---|---|
references/authentication.md |
OAuth 2.0 flow, token exchange, token refresh, distributed locking |
references/accounting_entities.md |
Customer, Invoice, Payment, Bill, JournalEntry CRUD payloads |
references/webhooks.md |
CloudEvents v1.0 payload, HMAC-SHA256 signature verification, async queue pattern |
references/queries_and_errors.md |
IDS-QL syntax, pagination, SQL injection prevention, exponential backoff |
references/ai_and_mcp.md |
QuickBooks MCP server deployment, LangGraph agent state machines |
Core Workflows
Workflow 1: OAuth 2.0 Token Lifecycle
[User clicks "Connect to QuickBooks"]
|
v
[Redirect to Intuit Authorization URL]
|
v
[User grants consent → receives ?code=...]
|
v
[POST /oauth2/v1/tokens/bearer (code exchange)]
|
v
[Store access_token (60 min) + refresh_token (100 days)]
|
v
[On 401 → POST /oauth2/v1/tokens/bearer (refresh grant)]
Critical: Encrypt both tokens at rest with AES-256-GCM. Use a distributed lock (e.g., Redis Redlock) to prevent concurrent refresh races.
Workflow 2: Robust Entity Update (SyncToken / Error 2030)
QuickBooks uses optimistic locking. Every entity carries a SyncToken. If another process updated the entity since your last read, the API returns error 2030 (Stale Object).
[POST update with local SyncToken]
|
+----+----+
| |
200 OK 400 / 2030
| |
[Done] [GET entity → get new SyncToken]
|
[Merge changes]
|
[POST update again]
Workflow 3: Asynchronous Webhook Processing
QuickBooks requires an HTTP 200 OK response within 3 seconds.
[Incoming POST from Intuit]
|
v
[1. Verify HMAC-SHA256 signature] ← raw bytes only, never parsed JSON
|
v
[2. Push raw payload to message queue (SQS / RabbitMQ / Redis)]
|
v
[3. Return HTTP 200 immediately]
|
v
[4. Background worker processes event]
API Quick Reference
Accounting Entities
| Entity | Endpoint | Methods |
|---|---|---|
| Customer | /v3/company/<realmId>/customer |
POST (create), POST (update sparse), GET |
| Vendor | /v3/company/<realmId>/vendor |
POST, GET |
| Invoice | /v3/company/<realmId>/invoice |
POST, GET, DELETE (void) |
| Payment | /v3/company/<realmId>/payment |
POST, GET |
| Bill | /v3/company/<realmId>/bill |
POST, GET |
| CreditMemo | /v3/company/<realmId>/creditmemo |
POST, GET |
| JournalEntry | /v3/company/<realmId>/journalentry |
POST, GET |
| Account (CoA) | /v3/company/<realmId>/account |
POST, GET |
| Item | /v3/company/<realmId>/item |
POST, GET |
| Deposit | /v3/company/<realmId>/deposit |
POST, GET |
| Transfer | /v3/company/<realmId>/transfer |
POST, GET |
Reports API
| Report | Endpoint | Key Params |
|---|---|---|
| Profit & Loss | /v3/company/<realmId>/reports/ProfitAndLoss |
start_date, end_date, accounting_method |
| Balance Sheet | /v3/company/<realmId>/reports/BalanceSheet |
date, accounting_method |
| General Ledger | /v3/company/<realmId>/reports/GeneralLedgerDetail |
start_date, end_date, columns |
| A/R Aging | /v3/company/<realmId>/reports/AgedReceivables |
report_date, aging_method |
Reports cell limit: 400,000 cells per response. Enforce a maximum 6-month date range per request to avoid timeouts.
Payments API (v4)
| Operation | Endpoint |
|---|---|
| Tokenize card | POST https://api.intuit.com/quickbooks/v4/payments/tokens |
| Create charge | POST https://api.intuit.com/quickbooks/v4/payments/charges |
| Refund charge | POST https://api.intuit.com/quickbooks/v4/payments/charges/<id>/refunds |
Batch Operations
Bundle up to 30 independent operations into a single POST request:
POST /v3/company/<realmId>/batch
Change Data Capture (CDC)
Retrieve all changed entities since a given timestamp:
GET /v3/company/<realmId>/cdc?entities=Customer,Invoice&changedSince=2026-05-31T00:00:00Z
Production Checklist
Before going live, verify:
- OAuth tokens encrypted at rest (AES-256-GCM).
- Distributed lock on token refresh (no concurrent refresh races).
- Exponential backoff with jitter on all API calls (handles
HTTP 429, 100 req/min limit). - IDS-QL inputs sanitized (escape single quotes to prevent injection).
- Reports date range capped at 6 months per request.
- Webhook signature verified on raw bytes before any JSON parsing.
- Webhook handler responds
HTTP 200within 3 seconds (async queue pattern). - PCI-DSS: raw card numbers never stored; use tokenization endpoint only.