QuickBooks Online Integration

CaseSolo's QuickBooks Online integration uses Intuit OAuth and the QuickBooks Online Accounting API directly. The launch path supports connection status, account mapping, invoice/payment/expense operations, CDC polling, reconciliation summaries, webhook activity capture, and replay for failed create operations.

Runtime Inputs

• QUICKBOOKS_CLIENT_ID and QUICKBOOKS_CLIENT_SECRET are required for OAuth.
• QUICKBOOKS_WEBHOOK_VERIFIER_TOKEN verifies Intuit webhook signatures when configured.
• Firm OAuth state is stored in firm.settings.quickbooksOAuth.
• Local admin preview state is stored in firm.settings.quickbooks and mirrored to OAuth config when a live connection exists.

Account Mapping

QBOConfig.accountMapping controls the QuickBooks IDs used by live payload builders:

• serviceItemId maps invoice lines to a QuickBooks product/service item. Default is 1, matching Intuit's common service-item example.
• bankAccountId maps expense purchases to an operating bank or credit-card account.
• expenseAccountId maps account-based expense lines.
• trustAccountId maps trust-account sync when enabled.
• paymentMethodId maps replayed/default payments to a tender type.

buildQBOAccountMappingReadiness() returns required and recommended mapping gaps. Expense sync requires both bankAccountId and expenseAccountId; trust-account sync requires trustAccountId.

Sync And Replay

• fetchChanges() uses QBO CDC for Invoice, Payment, and Purchase.
• runSync() pulls changed QBO entities, logs sync activity, processes the replay queue, and updates sync status.
• processErrorQueue() maps CaseSolo expense errors to QBO's /purchase endpoint because Intuit represents expenses as Purchase objects.
• Replay currently covers create-style payloads. Update/delete replay should stay gated until CaseSolo has SyncToken-aware mutation tracking.

Provider References

• Intuit CDC: https://developer.intuit.com/app/developer/qbo/docs/learn/explore-the-quickbooks-online-api/change-data-capture
• Intuit invoice workflow: https://developer.intuit.com/app/developer/qbo/docs/workflows/create-an-invoice
• Intuit Purchase API: https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/Purchase
• Intuit webhooks: https://developer.intuit.com/app/developer/qbo/docs/develop/webhooks

Verification

Run focused checks before changing provider behavior:

npm run test:run -- quickbooks
npx eslint src/lib/integrations/quickbooks.ts src/app/api/integrations/quickbooks/route.ts src/__tests__/lib/quickbooks-live.test.ts src/__tests__/api/quickbooks-integration.test.ts
npm run typecheck