Ambivo Books User Guide
DocsUG-090
QuickBooks Migration and Read-Only Mode
Migrating from QuickBooks, or running Books in read-only mode behind QuickBooks
Ambivo Books integrates with QuickBooks Online (QBO) in two distinct modes:
- Migration mode — One-time import of your QuickBooks data into Books, after which Books becomes your live system.
- System-of-record mode — QuickBooks stays your live invoicing system. Books mirrors invoices and bills for visibility but blocks creates / edits / deletes so the two cannot drift.
This guide covers both. Which mode you are in is set by your tenant administrator and cannot be changed casually.
Migration Mode (One-Time Import)
If you are switching off QuickBooks and onto Ambivo Books, this is your path.
What You Can Migrate
The Core Ambivo API's QuickBooks integration can pull:
- Chart of Accounts — All accounts with their types and codes
- Trial Balance — Account balances as of a chosen date (your switchover date)
- Customers — Names, addresses, contact details
- Vendors — Same fields
- Products / Items — Names, prices, default income/expense accounts
- Tax codes — Sales and purchase tax definitions
What You Cannot Migrate
- Historical transaction detail — Line-by-line invoices, bills, and payments before your switchover date. The Trial Balance carries the cumulative effect; per-transaction detail stays in QuickBooks.
- Memorized transactions / recurring schedules — These are QuickBooks-specific.
- Custom fields — Books does not yet support custom fields.
- Document attachments — Files attached in QuickBooks do not transfer.
Migration Steps
- Pick a switchover date. Typically the first day of a month or fiscal period.
- Reconcile QuickBooks through the day before the switchover date — you want the Trial Balance you migrate to be clean.
- Export your QuickBooks Chart of Accounts and Trial Balance as CSV.
- Import the Chart of Accounts in Books — see Data Import (UG-060) → Chart of Accounts.
- Import the Trial Balance as of the day before the switchover date — see Data Import (UG-060) → Trial Balance.
- Bring in Customers, Vendors, and Products through the Core Ambivo platform's import flow (the Books frontend does not have its own master-data importers today).
- From the switchover date, enter all new transactions in Ambivo Books.
- Keep your QuickBooks file as your historical archive — do not delete it.
Direct one-click QuickBooks → Books migration via Intuit OAuth is on the Core Ambivo roadmap; today's path is CSV-driven.
After Migration
Books is now your live system. QuickBooks becomes a read-only reference for periods before the switchover.
System-of-Record Mode (Read-Only Books)
If your organization is staying on QuickBooks but wants the Ambivo platform for CRM, sales, marketing, etc., your tenant is configured with invoicing_system = "quickbooks". In this mode:
- Invoices and bills are created and managed in QuickBooks
- Ambivo Books receives a synced view of them for visibility
- You can browse and view, but not edit, create, or delete
This keeps the two systems in sync without giving users two places to record the same data.
What Is Blocked in QuickBooks Mode
When invoicing_system = "quickbooks", the backend API blocks the following Books-side actions via the RequireInvoicingNotQuickbooks dependency:
| Resource | Blocked actions | Allowed actions |
|---|---|---|
| Invoices | Create, Update, Void, Delete | View, list, filter, export PDF |
| Bills | Create, Update, Pay, Void, Delete | View, list, filter, export PDF |
| Stripe Invoicing | Send via Stripe | (Not available in this mode) |
The API returns a clear error explaining why and pointing you to QuickBooks.
The frontend in QuickBooks-mode tenants typically still shows the create / edit buttons; the API rejection is what actually prevents the action. If your tenant is in QuickBooks mode and you find buttons surfacing in the UI, treat them as decorative — clicking them will produce an error rather than create or modify data. Tighter visual gating on the frontend (greying out or hiding the buttons up front) is on the cleanup list.
What Is Not Blocked
These continue to work normally:
- Browsing the customer and vendor lists
- Viewing reports
- Bank Feeds and Bank Transactions
- Journal entries (advanced — typically only accountants)
- Payments Received (recording incoming payments outside QuickBooks)
- Settings and configuration
How the Sync Works
The Core API's QuickBooks integration polls (or receives webhooks from) Intuit and pushes synced records into Books. Status changes flow through automatically — when an invoice is marked paid in QuickBooks, that status update arrives in Books, and the AR aging report reflects it.
There is sometimes a few-minute lag between an action in QuickBooks and its appearance in Books. If you suspect a sync gap, ask your tenant administrator to trigger a manual resync.
Why This Mode Exists
Some companies have legacy QuickBooks workflows, accountants who only know QuickBooks, or external integrations bolted onto QuickBooks. Forcing them off is disruptive. QuickBooks mode lets them get the benefit of the rest of the Ambivo platform while keeping QuickBooks as their accounting system of record.
Switching Modes
The mode is set on the tenant by the tenant administrator and is not a per-user toggle. Switching:
- From QuickBooks mode → Books-as-system-of-record — Treat as a migration. Sync any in-flight QuickBooks records into Books one final time, then change the mode and start treating Books as live.
- From Books → QuickBooks mode — Less common but possible. You stop entering invoices and bills in Books and start in QuickBooks; the existing Books history stays for reference.
In either direction, coordinate the switch carefully — and time it for an end-of-period boundary if you can.
Recognizing What Mode You Are In
Two cues:
- Look at your invoice and bill screens. If the + New Invoice / + New Bill buttons are missing or disabled with a tooltip, you are in QuickBooks mode.
- Check your tenant settings. The invoicing_system field — set in the Ambivo admin tools — is the source of truth. Ask your administrator if you are not sure.
Common Questions
Can a single tenant run some entities in QuickBooks mode and others in native mode?
The current setting is at tenant level, not per-entity. All entities in the tenant share the same mode.
My invoice in QuickBooks isn't showing in Books
Check sync timing — there is sometimes a small lag. If a record is stuck after several minutes, ask your administrator to check the QuickBooks integration in the Core API.
Can I record customer payments in Books while in QuickBooks mode?
Recording payments received through Books is not the same as creating an invoice; check with your administrator about exactly what is allowed for your tenant. The general principle: if QuickBooks is the system of record for invoices, payment recording typically also flows through QuickBooks to keep things consistent.
Why do I see invoices with weird IDs?
Synced records often carry the QuickBooks identifier as a reference field. Books shows it for traceability; the underlying numeric ID is internal.
Will reports be accurate in QuickBooks mode?
Yes — the synced data is what reports run on. As long as the sync is current, reports are as accurate as your QuickBooks data.
My organization wants to leave QuickBooks. Where do I start?
Plan a switchover date, reconcile QuickBooks through the day before, import COA + Trial Balance + masters, then start fresh on the switchover date in Books. See the Migration Steps section above.
What about QuickBooks Desktop (not Online)?
The integration is QuickBooks Online specific. For Desktop, your accountant would need to export and use the file imports manually.
Tips and Best Practices
- Migrate at a clean boundary. Day 1 of a month or quarter is the easiest to explain to your CPA.
- Reconcile QuickBooks through the migration date before importing. Garbage in, garbage out.
- Keep your QuickBooks file. Future audits and tax filings may need it.
- In QuickBooks mode, do not work around the blocks. If you need to create an invoice, do it in QuickBooks. Workarounds will desynchronize the two systems and create reconciliation pain.
- Coordinate mode changes through a single administrator. Two people switching the mode at different times is bad.
- Train your team on which system creates what. In QuickBooks mode the rule is "invoices and bills live in QuickBooks; everything else can happen in Ambivo." Make sure everyone knows.