ERPNext Africa · migration playbook
QuickBooks → ERPNext Migration Playbook
The simplest migration of the set — ERPNext ships a built-in QuickBooks Migrator for QuickBooks Online. The shared method still applies; this page covers the QB specifics.
◆ Originated under imbilawork for the ERPNext Africa venture · June 2026 · reusable IP
· The big shortcut: the native Migrator
ERPNext has a built-in QuickBooks MigratorIt connects to QuickBooks Online via OAuth and imports the Chart of Accounts, Customers, Suppliers, Items and transactions directly — no scripting for the common case. It suffixes imported accounts with
- QB to avoid collision with the default CoA. Review/clean the CoA in QBO first; reconcile opening balances after.For a typical small-business QBO file this can be near-turnkey — which is why QuickBooks clients are often the quickest wins for the venture.
· QuickBooks Online vs Desktop
| Source | Path |
|---|---|
| QuickBooks Online (QBO) | Use the ERPNext QuickBooks Migrator (OAuth) — recommended. Or the Intuit QBO REST API for bespoke needs. |
| QuickBooks Desktop | No direct connector — export lists & transactions to CSV (customers, vendors, CoA, items, invoices, payments) and import via Data Import; or convert the Desktop file to QBO first, then use the Migrator. |
· Mapping
| QuickBooks | → ERPNext |
|---|---|
| Chart of Accounts | Account (tree) — imported with - QB suffix by the Migrator |
| Customers / Vendors | Customer / Supplier |
| Items / Products & Services | Item |
| Invoices / Bills | Sales Invoice / Purchase Invoice |
| Payments / Bank transactions | Payment Entry / Journal Entry |
| Journal Entries | Journal Entry |
| Classes / Locations | Cost Center / Accounting Dimensions |
| Tax (VAT) codes | Tax templates (+ csf_za VAT) |
Even with the Migrator, the discipline holds: import masters & CoA first, then transactions, then reconcile opening balances against QuickBooks before go-live (see the SysPro playbook).
· Risks & gotchas
- CoA collision & the
- QBsuffix — decide whether to keep ERPNext's default CoA or the QB one; tidy duplicates post-import. - QuickBooks Desktop — no connector; CSV export quality varies, clean carefully (or convert to QBO).
- Classes/Locations — map to Dimensions/Cost Centers, not extra accounts.
- Opening balances — the Migrator imports data, but you still reconcile the trial balance, AR/AP aging and bank to the cent before go-live.
- SA VAT — confirm VAT mapping via
csf_zafor VAT201 with the accountant. - API throttling — large QBO files may need batching/retries via the Migrator/API.
Sources
ERPNext — QuickBooks Migrator docs · rtCamp — exporting QB data · Infintrix — QB→ERPNext · Solufy — QB→ERPNext · Intuit QuickBooks API · shared method: SysPro → ERPNext playbook