Each TradelyHQ tenant connects their OWN QuickBooks Online account via OAuth. We never see your QBO data; you never see another tenant's. The connection is per-tenant, scoped, and revocable.
Connecting QuickBooks
- Open Settings → Integrations in your admin portal
- Click Connect QuickBooks
- You'll be redirected to Intuit's OAuth flow — sign in with your QBO admin credentials
- Approve the connection. Intuit redirects you back to TradelyHQ
- You're connected. Tokens are encrypted at rest in
tenant_provider_keys
What syncs automatically
- Invoice push: when you click "Authorize & Send" on an invoice in TradelyHQ, it's created in QBO immediately
- Payment status pull: QBO webhooks back when a payment is recorded; TradelyHQ flips the invoice status to "paid" automatically
- Customer mirror: first time you push an invoice for a client, that client is mirrored as a QBO Customer record
- Item mirror: line items are mirrored to QBO Items the first time they appear on an invoice
The nightly reconcile
At 2 AM your tenant's local time, a cron job runs through every invoice and verifies QBO's view matches TradelyHQ's view. If something drifted (someone hand-edited the invoice in QBO, network hiccup during the original push, etc.), the discrepancy lands in the Sync Errors panel for an admin to review.
What's NOT bidirectional
Today, only invoices sync from TradelyHQ → QBO. We don't pull customers, items, or chart-of-accounts from QBO into TradelyHQ. Two reasons:
- Customer/item names overlap awkwardly with our client/wo concepts
- You generally want TradelyHQ as the system-of-record for jobs and invoicing flow; QBO as the system-of-record for general ledger
Disconnecting
Same Settings → Integrations panel. Tokens are revoked at Intuit's side AND deleted from tenant_provider_keys. Existing invoices already pushed stay in QBO unchanged.
If something looks wrong
The Sync Errors panel surfaces every invoice where TradelyHQ and QBO disagree. Most common causes: (1) you hand-edited an invoice in QBO, (2) your QBO subscription lapsed and the OAuth token revoked, (3) a transient network error. Click the error for a re-sync option.
If your QBO connection token expires or is revoked, you'll see a "Reconnect QuickBooks" banner at the top of the Sync Errors panel. Re-doing the OAuth flow restores the connection without touching any existing invoices.