name: quickbooks-api
description: "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."
version: 1.0.0
metadata:
openclaw:
primaryEnv: QUICKBOOKSCLIENTID
requires:
env:

• QUICKBOOKSCLIENTID
• QUICKBOOKSCLIENTSECRET
• QUICKBOOKSREFRESHTOKEN
• QUICKBOOKSREALMID

envVars:

• name: QUICKBOOKSCLIENTID

required: true
description: OAuth 2.0 Client ID from the Intuit Developer Portal.

• name: QUICKBOOKSCLIENTSECRET

required: true
description: OAuth 2.0 Client Secret from the Intuit Developer Portal.

• name: QUICKBOOKSREFRESHTOKEN

required: true
description: Long-lived OAuth 2.0 refresh token (valid for 100 days). Used to obtain new access tokens.

• name: QUICKBOOKSREALMID

required: true
description: The QuickBooks Online company ID (realmId) obtained after the user completes the OAuth authorization flow.

• name: QUICKBOOKS_ENVIRONMENT

required: false
description: "API environment to target. Accepted values: 'sandbox' (default) or 'production'."

• name: QUICKBOOKSVERIFIERTOKEN

required: false
description: Webhook verifier token from the Intuit Developer Portal. Required only when processing incoming webhook events.
emoji: "📒"
homepage: https://developer.intuit.com/app/developer/qbo/docs/learn/explore-the-quickbooks-online-api

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