QuickBooks Online Sync
What syncs, which fields map where, how to trigger a manual push, and how to fix it when something drifts.
What syncs to QuickBooks?
Three things sync: Customers (as QB Customer records), Invoices (as QB Invoice records with line items and tax), and Expenses (as QB Purchase records). Syncing is manual — you push when you're ready. The exception is payment status: if QB marks an invoice fully paid, Kontrol™ automatically updates the invoice to PAID.
How to connect QuickBooks
Go to Settings → Integrations → QuickBooks. Click "Connect QuickBooks Online". Sign in to Intuit and grant access. You're redirected back to Kontrol™ with the connection active. Your access token refreshes automatically every hour — you'll only need to reconnect after 100 days or if you revoke access from inside QuickBooks.
What each field maps to in QB
Customer: companyName → DisplayName + CompanyName, contactName → GivenName + FamilyName, email → PrimaryEmailAddr, phone → PrimaryPhone, address fields → BillAddr. Invoice: invoiceNumber → DocNumber, line items → QB Line objects, taxAmount → separate line item (e.g. "Tax (8.5%)"), notes → CustomerMemo. Expense: vendor → EntityRef, paymentMethod → PaymentType, category → AccountRef. Full field-by-field tables are in the detailed guide.
A customer must have an email address before they can be synced to QB. QB requires it for every Customer record.
Triggering a manual re-sync
Customer: Customers → [Customer] → QuickBooks panel → Sync. Invoice: Jobs → [Job] → Invoices tab → Sync to QB. Expense: Expenses → [Expense] → Sync to QB. All sync operations are safe to run more than once — if the record already exists in QB, it updates in place.
When QB and Kontrol™ disagree (conflicts)
If someone edits a record directly in QuickBooks after it was synced, Kontrol™ detects the difference on the next QB webhook. A conflict record is created for admin review. You have three options: keep Kontrol™'s values, apply QB's values, or dismiss the conflict. The only auto-apply case is when QB shows an invoice as fully paid — that update is applied automatically without creating a conflict.
Never delete a synced invoice in QuickBooks. Void it instead. Deletion breaks the sync link and can cause errors on the next push.
Common errors and fixes
"No active QuickBooks connection" → reconnect in Settings → Integrations. "Token refresh failed" → your 100-day refresh token expired; disconnect and reconnect. "Failed to sync customer" → customer is missing an email address. "QB API error (400)" → stale SyncToken (someone edited the QB record); just run the sync again — it self-heals. "QB API error (429)" → rate limited; wait 60 seconds and retry.
Fixing a duplicate invoice in QB
If the same invoice was accidentally synced twice: (1) Void the duplicate in QuickBooks Online — do not delete it. (2) If Kontrol™'s QB Invoice ID points to the voided record, clear it in the database so it can be re-created. (3) Re-sync the invoice to create a fresh record. (4) Resolve or dismiss any open conflict records for this invoice.