Intuit-quickbook

Production-grade integration and automation with the QuickBooks Online API. Covers OAuth 2.0 authentication, accounting entities (Customers, Invoices, Payments, Bills, Journal Entries), real-time Webhooks, Reports API, Payments API, IDS query language, Change Data Capture, Batch operations, and AI/MCP server integration.

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

text

[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).

text

[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.

text

[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:

text

POST /v3/company/<realmId>/batch

Change Data Capture (CDC)

Retrieve all changed entities since a given timestamp:

text

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 200 within 3 seconds (async queue pattern).
• PCI-DSS: raw card numbers never stored; use tokenization endpoint only.