Migration Checklist: Moving to Odoo ERP

Phase 0

Decide & Plan

Lock scope, deployment shape, edition, and localization before any data moves.

• Decide and document the Odoo deployment target. Choose Odoo Online (SaaS, no custom server-side code, throttled write throughput), Odoo.sh (managed PostgreSQL with staging branches and shell access), or on-premise (full control over filestore, workers, and ir.config_parameter). Each path has different access to shell, database manager, and per-file caps.

  Risk if skipped: Picking Odoo Online and then discovering you need a custom localization module or server action forces a re-platform mid-project.

• Decide between Community and Enterprise edition. Community is free but excludes the full Accounting app, Studio, the Documents app, OCR on bills, MRP master production schedule, and several l10n_* localization modules. Confirm which account.*, mrp.*, and stock.* features the target workflow requires before purchase.

  Risk if skipped: Restoring an Enterprise database into a Community container marks Enterprise modules as 'not installable, skipped' and breaks the Accounting app entirely on Community.

• Pin the exact Odoo major version for the cutover. Pin Odoo 17, 18, or 19 before mapping. View XML, model names, and Selection options shift between majors (e.g. <tree> became <list> in 18). For migrations between major versions of an existing Odoo database, plan for the OpenUpgrade tooling path rather than treating it as a fresh import.

  Risk if skipped: Mapping against the wrong major produces import files referencing fields that have been renamed or removed.

• Pick the l10n_* localization module per country of operation. Each country has a dedicated chart-of-accounts and tax module (e.g. l10n_us, l10n_de, l10n_fr, l10n_in). Choose one per res.company before any account.account record is created — switching the localization after accounts exist is not supported.

  Risk if skipped: Switching localizations post-load forces a database rebuild because the chart-of-accounts template is one-shot.

• Define migration scope by Odoo model. List in-scope models explicitly: res.company, res.partner, account.account, account.journal, account.move, account.payment, product.template, product.product, uom.uom, stock.location, stock.warehouse, stock.lot, stock.quant, mrp.bom, mrp.bom.line, res.currency, res.currency.rate. Mark each as in or out of scope.
• Define the historical-data window for posted journals. Decide how many fiscal years of posted account.move records migrate as posted documents versus collapse into a single opening-balance journal. The standard convention is: prior closed years collapse into one opening journal; the current open year migrates as posted documents.

  Risk if skipped: Migrating five years of posted journals when only opening balances are needed inflates database size by an order of magnitude and slows every report.

• Decide the multi-company structure. Map source legal entities to res.company records. Decide whether each company gets its own chart-of-accounts (separate l10n_* installs) or shares one. Document the parent_id hierarchy if companies consolidate.
• Identify legal, residency, and retention constraints. Confirm the Odoo.sh region matches data-residency obligations. As of 2026, Odoo.sh has seven data center regions: Iowa, Toronto, Saint-Ghislain, Dammam, Mumbai, Singapore, Sydney. Document GDPR data-subject access and erasure procedures against res.partner and account.move. Document audit-log retention for financial records.

  Risk if skipped: Discovering a residency conflict after go-live forces a database export, region re-provision, and re-import.

• Assign a single Directly Responsible Individual plus a finance approver. Name one accountable owner with authority to cut scope and one finance approver who signs the opening trial balance and the post-load reconciliation in writing.
• Set the cutover window and source-system freeze date. Pick the cutover datetime in the destination timezone. Align it to a period close in the source so the opening balance has a clean cutoff. Communicate both to all source users at least four weeks in advance.
• Document the migration success criteria. Write the falsifiable conditions: opening trial balance ties to source to the cent, every open AR/AP invoice exists in Odoo with matching residual, stock-on-hand per stock.location matches source, BOMs explode to the same components, multi-currency unrealized gain/loss reconciles.

  Risk if skipped: Without explicit success criteria the project never formally closes and finance refuses sign-off.

• List explicit out-of-scope items. Capture items intentionally excluded (e.g. closed work orders older than three years, deprecated stock locations, retired products with zero on-hand). Out-of-scope items become scope creep without this list.

Phase 1

Pre-Migration Prep

Everything that must be true before the first byte leaves the source.

Phase 2

Source Export

Pull a complete, timestamped snapshot of master data, transactions, and configuration.

• Export all source customers and vendors with every standard and custom field. Include the source's primary key as a column — this becomes the Odoo external ID. Capture VAT/tax-ID, payment terms, and price list assignment.

  Risk if skipped: Forgetting the source ID column makes idempotent re-runs impossible and forces full re-imports.

• Export the source chart of accounts with account code, name, type, and parent. This is the input to mapping into account.account. Capture currency_id per foreign-currency account.
• Export the closing trial balance as of the cutover cut date. Per-account debit and credit totals for the closing of the period before cutover. This becomes the opening-balance journal entry in Phase 3.

  Risk if skipped: An unsigned or untimed trial balance produces an opening journal that finance cannot trace back to a source document.

• Export open AR invoices with line detail. Include invoice number, date, due date, partner, currency, lines with account, tax, and amount, plus current residual. Closed invoices stay in the legacy system unless the historical window says otherwise.
• Export open AP bills with line detail. Same shape as AR. These become posted account.move records of type 'in_invoice' in Odoo.
• Export posted journal entries inside the historical window. If the historical-data window in Phase 0 includes posted prior-year journals, export them as account.move plus account.move.line rows. Include journal code, date, partner_id, account code per line, debit, credit, currency.
• Export products with template, variant, BOM, and routing data. Separate files for product.template, product.product (variants), product.attribute, mrp.bom, mrp.bom.line, and mrp.routing. Capture cost, list_price, uom_id, uom_po_id, and the responsible employee.
• Export stock-on-hand per location, lot, and serial. This becomes the stock.quant opening file. Each row needs product, location, quantity, lot/serial number (if tracked), reserved quantity, and valuation cost.

  Risk if skipped: Missing the lot/serial column on a serial-tracked product forces individual quant rows to be split manually post-load.

• Export bills of materials and BOM lines. mrp.bom (header: product, qty, type) plus mrp.bom.line (component product, qty, uom). Multi-level BOMs export the full tree, not flattened — Odoo recomputes the flatten on demand.
• Export multi-currency historical exchange rates. Capture dated rate rows per currency for every date that has a transaction in scope. Without these, foreign-currency journal entries cannot post.

  Risk if skipped: Skipping historical rate export forces a fallback to today's rate and misstates every multi-currency open balance.

• Export pricelists, payment terms, and tax codes used by source documents. product.pricelist + product.pricelist.item, account.payment.term + account.payment.term.line, account.tax. These are referenced by transactional records and must exist before load.
• Export attachments as binaries plus a metadata manifest. Download every bill, invoice, contract, and product spec sheet. Produce a manifest CSV with source attachment ID, original filename, MIME type, file size, related model, related record ID.

  Risk if skipped: Files without a manifest cannot be re-linked to their parent records and become orphaned uploads.

• Export the source user list with roles and reporting structure. User → email mapping drives the salesperson lookup, the responsible-purchaser lookup, and the ownership assignment.
• Capture screenshots and config exports of source automations and reports. Source workflows, dashboards, and reports do not transfer. Document them so they can be rebuilt manually post-cutover.
• Record the exact timestamp of every export. The delta between export time and cutover time becomes the change set you must re-pull at cutover. Date-stamp every file in its filename.

  Risk if skipped: Without an export timestamp you cannot compute the delta and risk losing every change made between export and cutover.

• Hash each exported file and store the hash alongside the export. SHA-256 of each CSV and binary. The hash proves you imported the exact bytes you exported during validation.

Phase 3

Transform & Map

Reshape source exports into Odoo-shaped CSVs.

Phase 4

Sandbox Test Migration

Run the full migration against a duplicate database before touching production.

• Refresh the sandbox database from the latest production config. Use 'Duplicate Database' or rebuild the Odoo.sh staging branch from production. Confirm modules, users, l10n_*, account.journal, and stock.warehouse records match.
• Load a representative 1–5% sample of each model into the sandbox. Use Settings → Apps → Import or the list view → Favorites → Import records. Upload the sample CSV and verify the matching screen recognizes every column.

  Risk if skipped: Loading the full file first burns hours debugging issues a 1% sample would have caught in minutes.

• Test the opening-balance journal entry in sandbox. Post the full opening account.move, then run the trial balance report. Debits and credits must equal and tie to the source trial balance to the cent.

  Risk if skipped: An out-of-balance opening journal blocks every subsequent posted invoice from reconciling cleanly.

• Test stock.quant load and verify Inventory → Reporting → Stock Valuation. Run the opening stock load, then check stock-by-location reports against the source. Confirm fractional quantities (e.g. 1.36 kg) survive the dot-decimal transform.

  Risk if skipped: Stock valuation that does not tie post-load forces every product category's costing method to be re-validated.

• Test BOM explosion against a known finished good. Pick a multi-level BOM. Open Manufacturing → Products → BOM Structure. Expand the tree and compare component quantities to the source BOM.

  Risk if skipped: A flattened or partial BOM produces incorrect material requirements for every future manufacturing order.

• Test multi-currency posting against the dated rate. Post a foreign-currency invoice with an invoice_date matching a seeded res.currency.rate row. Confirm Odoo computes the amount_company_signed using the dated rate, not today's rate.

  Risk if skipped: Wrong rate selection misstates every foreign-currency residual and breaks AR reconciliation.

• Test field-by-field on 10 random sandbox records per model. Open each in the form view and compare every field to the source. Pay extra attention to Selection fields, dates, Many2one references, and tax_ids on invoice lines.

  Risk if skipped: Bulk count matches can mask field-level corruption that only field-by-field comparison surfaces.

• Test long-string, special-character, and emoji cases explicitly. Include in the sample at least one record per model with a 4000-character body, embedded commas and quotes, an accented character in a partner name, and a CJK product description.
• Test NULL handling for every nullable field. Include sample rows where every nullable field is blank. Confirm Odoo accepts the blank without substituting a default or zero.
• Test parent-child relationships (res.partner.parent_id, product.product.product_tmpl_id). Load companies first, then contacts. Open a contact and confirm the Company field is populated and clicking through opens the company record. Same for product variants under a template.
• Test attachment download from imported ir.attachment records. Open a sample of invoices and products with attachments. Click each file and confirm it downloads with correct content and filename.
• Run a full-volume test if sandbox capacity permits. If the sandbox can hold the full volume, run the entire import end-to-end. Time each model's load step and extrapolate to the production cutover budget.

  Risk if skipped: Skipping a full-volume rehearsal means cutover-day surprises around throttling, timeout behavior, and storage caps.

• Measure load throughput against the hosting tier. Odoo Online throttles aggressively per session. Plan batch sizes (50–200 records per load() call) accordingly and add exponential backoff on throttle responses. Standard performance ceiling is 2–3 sales orders per second per worker.

  Risk if skipped: Aggressive parallel writes against Odoo Online trip throttling and stall the load mid-batch.

• Have a finance domain expert spot-check 25 sandbox journal entries. Pick records they recognize. Ask them to flag anything that 'looks wrong' in account assignment, tax treatment, or currency. Their tacit knowledge surfaces issues no checklist catches.
• Re-run the import idempotently to confirm upsert behavior. Run the same file again. Row counts should remain identical, not double. If counts double, the external-ID column is missing or wrong.

  Risk if skipped: Non-idempotent imports compound every retry into duplicate journals and force a destructive cleanup.

• Capture sandbox sign-off in writing before proceeding to Phase 5. Migration sponsor, finance approver, and IT confirm the sandbox passes. Without this gate the production cutover cannot start.

Phase 5

Production Cutover

Sequenced execution window — one shot, fully scripted.

• Confirm freeze on the source system. Verify with the source system audit log that no writes have occurred in the last 60 minutes. Lock down user permissions on the source if possible.

  Risk if skipped: Late source writes that arrive after the final export become silent data loss.

• Take the final delta export from the source. Re-export every in-scope object, capturing only records modified since the Phase 2 baseline timestamp. Re-pull the trial balance as of the freeze instant.
• Disable Odoo automated actions and outgoing mail during the load. Settings → Technical → Automation → Automated Actions: pause every rule on the models being loaded. Disable the outgoing mail server temporarily to avoid notification storms.

  Risk if skipped: Active automations during bulk load fire thousands of redundant notifications and corrupt computed-field state.

• Take a pre-load backup of the destination database. Database manager → backup, or on Odoo.sh use the auto-snapshot before deploy. Confirm the backup downloads and is restorable to a scratch database.
• Load res.users first. Upsert users by login email. Confirm row counts match the user export.
• Load configuration records: res.currency.rate, uom.uom, account.account, account.journal, account.tax, account.payment.term. These should already exist from Phase 1b; this step idempotently confirms and adds any new rate rows captured in the delta. Verify journal codes and tax rates against the source one more time before any account.move loads.
• Load res.partner companies first, then contacts. Companies (is_company=True) before contacts (is_company=False with parent_id). Confirm post-load counts before continuing.
• Load product.category, product.template, product.product, then stock.warehouse, stock.location, stock.lot. Templates before variants; warehouse and location tree before stock.quant. Pre-create every lot/serial number a tracked product will reference. Use external-ID upsert mode and capture import job IDs.
• Load mrp.bom and mrp.bom.line. BOM headers before BOM lines. Multi-level BOMs load in topological order: leaf components first, then assemblies that reference them.

  Risk if skipped: Loading mrp.bom.line before its parent mrp.bom triggers ondelete='cascade' foreign-key violations and discards the line.

• Post the opening-balance journal entry. Load the opening account.move as draft, run the trial-balance sanity check inside Odoo, then post the entry (write state='posted' or call action_post). Lock the fiscal year for the prior period immediately after posting.

  Risk if skipped: Posting the opening journal before BOMs and products exist leaves the GL balanced but disconnected from inventory valuation, producing reconciliation drift.

• Load stock.quant opening on-hand via the inventory adjustment journal. Create one stock.inventory record (or stock.quant inventory_quantity field in 18+) per location-product, then apply to seed on-hand. Do not write directly to stock.quant in production.

  Risk if skipped: Direct writes break Odoo's stock valuation accounting entries and cause the inventory account to drift from physical on-hand.

• Load open AR invoices and AP bills as posted account.move records. AR uses move_type='out_invoice' with state='posted' and the receivable account on each line. AP uses move_type='in_invoice' with the payable account. Verify partner_id, account_id, and invoice_date match. Cross-check residual sum against open-AR and open-AP aging from the source.
• Load posted prior-year journal entries if in scope. If the historical-data window includes posted prior-year journals, load them after the opening journal and against the locked prior fiscal year. Unlock the lock date temporarily for this load, then re-lock.

  Risk if skipped: Loading prior-year journals without re-locking afterward leaves the prior period writable and exposes the opening balance to drift.

• Load ir.attachment binaries last. Stream binaries via create() with base64-encoded datas, res_model, and res_id. Throttle to the hosting tier's throughput ceiling. Confirm one sampled file downloads correctly mid-load.

  Risk if skipped: Pushing attachments above the per-file cap or beyond the hosting throughput ceiling causes silent failures that orphan the parent record.

• Cross-check destination row counts and totals against source at each step. After every model, run search_count and compare to the export's row count. After the opening journal, run the trial-balance report and tie to source. Investigate any delta before proceeding.

  Risk if skipped: Cascading row-count and total drift across models compounds and becomes unprovable later.

• On any partial-load failure, stop, diagnose, and re-run idempotently. Do not push through with partial data. The external-ID upsert key makes safe re-runs possible — use it.
• Re-enable automated actions and outgoing mail after all loads complete. Restore automation rules and the outgoing mail server. Run one end-to-end test (create vendor bill, post, register payment) to confirm automations fire as expected.

Phase 6

Validate

Prove correctness before users get the keys.

Phase 7

Post-Migration Cleanup

Decommission the source, retire migration scaffolding, capture lessons.

• Send go-live communication to all end users. Include Odoo login URL, password-reset instructions, the first-responder contact for issues, and a one-page 'how the new modules map to the old workflow' cheat sheet.
• Run role-segmented training sessions. Accounting (journals, reconciliation, period close), Inventory (transfers, scrap, valuation), Manufacturing (work orders, MPS), Sales/Purchase (quotations, vendor bills), admins (Settings, Studio if Enterprise, user provisioning). Record each session.
• Set the source system to read-only. Strip write permissions for all users. Communicate the read-only date in writing. Keep read access during the post-migration safety window.
• Rebuild reports and dashboards inside Odoo. Source reports do not transfer. Use Odoo's pivot, graph, and list views with saved Favorites. Enterprise users can also build dashboards via the Spreadsheet app.

  Risk if skipped: Finance leadership without their reports stops trusting the migrated data even when it is correct.

• Rebuild source automations as Odoo automated actions. Settings → Technical → Automation → Automated Actions for trigger-based rules. Settings → Technical → Server Actions for code-based logic. Test each rule before enabling.
• Schedule scheduled actions for the recurring jobs. Settings → Technical → Scheduled Actions for cron jobs (invoice reminders, stock reordering, currency rate refresh from a service). Confirm each runs on the planned cadence.
• Re-establish integrations to other systems. Banking feeds, payment gateways, EDI partners, shipping carriers, BI tools. Use a dedicated service-account user for access.
• Disable the migration_bot user. The bulk-load credentials are no longer needed and represent an oversized access surface. Disable the user to lock it out of routine use.

  Risk if skipped: Active migration-tier credentials become the path of least resistance for accidental or malicious bulk writes to the GL.

• Confirm the period-close workflow for the first cutover-month close. Walk finance through the first end-of-month close in Odoo: lock dates advance, recurring journals post, bank reconciliation completes, financial reports run. Capture issues for the next month.

  Risk if skipped: An untested first period close becomes a fire drill at month-end and undermines confidence in the migration.

• Schedule the 30-day post-migration retrospective. Capture what went well, what did not, what would change. File the notes with the migration record so the next migration starts ahead.
• Document the source-system decommission date. Typically 90 days after cutover and at least one full period-close cycle. Capture in the migration record with the named approver. Retain the source database as a read-only archive for the documented audit window (often seven years for financial records).
• Archive the source-system exports and the migration files to long-term storage. Encrypted cold storage retains the Phase 2 baseline, Phase 5 delta, mapping spreadsheet, and post-load sign-off for the documented retention window. Capture storage location and access process.
• Close the migration project formally. Final status report, lessons-learned document, project closure note. Reassign the DRI back to their regular role.