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

All requests require the header Authorization: Bearer \x3Caccess_token> and Accept: application/json.

Reference Guides

Detailed schemas and code implementations are in the references/ folder. Load them as needed:

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

Reports API

Reports cell limit: 400,000 cells per response. Enforce a maximum 6-month date range per request to avoid timeouts.

Payments API (v4)

Batch Operations

Bundle up to 30 independent operations into a single POST request:

POST /v3/company/\x3CrealmId>/batch

Change Data Capture (CDC)

Retrieve all changed entities since a given timestamp:

GET /v3/company/\x3CrealmId>/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.