QuickBooks Integration Hub

QuickBooks Online (QBO) is the accounting platform for RERI financial operations — invoices, customers, payments, and chart of accounts. Integration is LOW priority / not yet wired in OpenClaw as of 2026-03-04 (per KB notes). The relevant agents are atlas (financial reporting) and betterescrows (escrow fee tracking). Read this hub before any financial reporting integration, QBO sync, or invoice automation work.

Quick reference

Field	Value
Vendor	Intuit QuickBooks Online
URL	https://quickbooks.intuit.com
KB doc	API
Auth method	OAuth 2.0 (Authorization Code flow)
Auth credential	op://Aurora/quickbooks/access-token
OAuth cred (client)	op://Aurora/quickbooks/client-id, op://Aurora/quickbooks/client-secret
Refresh token	op://Aurora/quickbooks/refresh-token (expires 101 days)
Cred-proxy port	n/a (until NemoClaw B1-B6 ratified)
Webhook port	n/a (not currently wired)
Webhook handler	n/a
Webhook dedup table	n/a
Tunnel path	n/a
Outbound API base	https://quickbooks.api.intuit.com/v3/company/{realmId}/
Sandbox base	https://sandbox-quickbooks.api.intuit.com
API version	v3, minorversion=73
Rate limits	500 req/minute per realm; 429 → exp backoff (retry-after header)
Rate-limit action	429 → wait retry-after seconds, then retry; Discord ops after 3 consecutive failures
Cost	QBO subscription (existing); API access included
Backup/recovery	Intuit-owned; no PITR; export via QBO UI quarterly
Discord alert channel	ops
Drift cadence	on-API-change
Status	production

OAuth token lifecycle

Token	Expiry	Action
Access token	1 hour	Auto-refresh via refresh_token grant
Refresh token	101 days	Manual re-auth; cron alert at 90d to prompt renewal
realmId	Permanent (per company)	Store alongside tokens; required in all API URLs

Critical: QBO uses SyncToken optimistic locking — always GET the current object before any POST update, or get error 3200. Re-read → merge → POST pattern required.

Components

• workspace/knowledge-base/quickbooks/API.md — Full API reference: OAuth flow, endpoints (company, customers, invoices, payments, items, accounts), QQL query language, error codes
• workspace/knowledge-base/quickbooks/examples/ — Code examples directory
• _summary — Financial reporting; primary QBO consumer candidate
• _summary — Escrow fee tracking; secondary QBO consumer candidate

How it’s used

• Current state: NOT integrated in OpenClaw as of 2026-03-04. Credentials pending setup.
• Planned trigger: Atlas agent receives deal-closed event → creates QBO invoice for commission; betterescrows agent creates QBO payment record on escrow close
• Workflow: HubSpot deal stage “Closed Won” → Atlas → POST /v3/company/{realmId}/invoice → email invoice to counterparty
• Agents involved: atlas (reporting + invoicing), betterescrows (escrow accounting)
• Failure mode: OAuth refresh token expiry (101 days) → all calls return 401; re-auth via Intuit OAuth flow
• Failure mode 2: SyncToken conflict (3200) → re-read entity and retry
• Success criteria: Invoice created with correct CustomerRef, Line items, DueDate; payment applied against invoice balance = 0

Key API patterns

URL structure

https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}?minorversion=73
Authorization: Bearer {access_token}
Accept: application/json

QQL (QuickBooks Query Language)

SELECT * FROM Invoice WHERE Balance > '0' AND CustomerRef = '{customerId}'
SELECT * FROM Payment WHERE TxnDate >= '2026-01-01'

SyncToken update pattern (MANDATORY)

1. GET /customer/{id} — fetch current object + SyncToken
2. Merge updates with full current object
3. POST /customer with Id + SyncToken + all fields

Cross-links

Agents that touch this

• _summary — financial reporting; primary QBO integration owner
• _summary — escrow fee + payment tracking

Skills that invoke this

• betterfiles-cda — CDA (Commission Disbursement Allocation) generation; QBO invoice creation is adjacent workflow

Plans that govern this

• vendor-deep-audit-comprehensive-2026-05-02 — QBO included in vendor baseline (104 vendors, 4,750 findings)
• openclaw-fragmentation-fix-2026-05-01 — financial data layer in scope

Feedback rules

• feedback_no_plaintext_creds — OAuth tokens must stay in 1Password, never in .credentials plaintext
• feedback_verify_schema_before_designing — always check SyncToken pattern before writing update logic
• feedback_live_over_memory — test against QBO sandbox before production; do not assume field names

KB / source docs

• API — Full QBO API reference (last verified 2026-03-04)

System maps

• cost-flow — financial reporting chain: QBO → Atlas reporting
• deal-lifecycle-map — deal-close triggers QBO invoice creation (planned)

Related: Credential layer cluster

All OAuth tokens stored in 1Password vault Aurora. See 1password for op:// CLI access pattern. Credentials: op://Aurora/quickbooks/access-token, op://Aurora/quickbooks/refresh-token, op://Aurora/quickbooks/client-id, op://Aurora/quickbooks/client-secret, op://Aurora/quickbooks/realm-id. Store realmId alongside tokens — it is required in every API URL.

Token refresh cron: Implement 90-day cron to alert before 101-day refresh token expiry. Pattern similar to SalesMsg token refresh (see salesmsg).

Related: Financial reporting cluster

• stripe — payment processing; QBO invoices may reference Stripe payment IDs as payment method
• hubspot — HubSpot deal “Closed Won” triggers QBO invoice creation in planned workflow; deal ID cross-referenced in QBO PrivateNote

Open issues / TODOs

• QBO integration is NOT YET wired in OpenClaw (as of 2026-03-04 KB note) — confirm current status before building
• Setup required: create OAuth app in Intuit Developer Dashboard, store client_id, client_secret, realm_id in 1Password vault Aurora
• Token refresh cron: add 90-day alert before refresh token expires (101-day window); cron pattern similar to SalesMsg
• Identify realmId for RERI production company and store in 1Password
• Plan: Atlas agent integration — define which deal events trigger QBO invoice/payment writes
• Sandbox testing required before production integration (sandbox-quickbooks.api.intuit.com)

Recent activity

• 2026-05-04: hub created (W3-S5, Wave 3)
• 2026-03-04: API.md verified (OAuth 2.0 flow, endpoints, QQL, rate limits — status: COMPLETE)