The Definitive Guide to Migrating to Odoo CRM

Odoo S.A. was founded by Fabien Pinckaers in 2005 as TinyERP, rebranded to OpenERP in 2009, then to Odoo in 2014, and is headquartered in Ramillies-Brabant-Wallon, Belgium ¹. Odoo CRM is the sales-side application inside a suite of around 80 official modules — Sales, Inventory, Accounting, Manufacturing, HR, Project, Website, eCommerce — all sharing the same PostgreSQL database and ORM.

The typical Odoo CRM customer is a small-to-mid-market team — 10 to 300 users — that wants pipeline plus quoting plus invoicing plus inventory under one schema, and is willing to absorb the open-source learning curve in exchange for the integration depth. Compared with HubSpot or Pipedrive, Odoo positions itself on integrated business operations and Community-edition affordability; compared with Salesforce, it positions on a unified data model and a far smaller per-user cost on Enterprise tiers.

The shapes of migration that actually land on Odoo CRM tend to fall into four patterns. First, suite consolidation projects: a company replacing a stack of Pipeline CRM plus QuickBooks plus a separate inventory tool with the Odoo all-in-one suite. Second, vendor-cost exits from Salesforce or Zoho where total cost of ownership on smaller teams justified an open-source alternative ³.

Third, legacy replacements — older OpenERP/TinyERP installs, Sage, Microsoft Dynamics on-prem, or homegrown databases — where the source schema is loose and the project is really a re-architecture against crm.lead and res.partner. Fourth, Odoo-to-Odoo version migration, where a team running Community 15 jumps to 18 or 19, or moves from Odoo.sh Enterprise back to self-hosted Community ⁴.

Each shape has a different difficulty profile: a Pipeline CRM migration usually has clean object parity but messy custom-field labels, while a Salesforce migration carries rich automation that does not move across.

What makes migrating *to* Odoo CRM easier than the category average is the import tool itself — it accepts CSV and Excel files, auto-detects column types, supports relational fields via XML external IDs, and ships built into every model's list view through Actions → Import records ⁵⁶. Pre-built templates exist for Contacts, Leads, Companies and Products.

What makes it harder than the average is the Community-vs-Enterprise gap, where Studio, advanced reporting, the Marketing Automation app and several connector modules are paid-only and silently disappear if you restore an Enterprise database into a Community container ⁴. The second hard edge is the per-tenant throughput ceiling on Odoo Online of roughly one programmatic request per second — a constraint that catches teams scaling parallelism off database-server expectations ⁸.

Studio customisations, custom Python modules, automated actions and server actions do not move with a CSV import — they are rebuilt as modules and configured in the destination. Teams that scope for that work up front finish on time; teams that assume parity do not.

Studio customisations, custom modules and server actions do not move with a CSV import — they are rebuilt in the destination.

Odoo's CRM is built around a small set of Python models, each declared as a class extending models.Model with attributes that the ORM persists into PostgreSQL ⁹. Sales activity and pipeline behaviour sit on top of the same shared res.partner master record used by Accounting, Sales, and every other Odoo app.

Before you can map a field on the source side, you need to know exactly which destination model the row belongs on, what fields it requires, and which value will serve as its external ID for upsert. The table below summarises the models you will touch in an Odoo CRM migration ¹⁰.

res.partner is the unifying record — a single row represents either a person (is_company=False) or a company (is_company=True), and the parent-child relationship between an employee and their employer is modelled by the parent_id Many2one field on res.partner itself ¹¹.

Odoo does not have a single canonical natural-key field like HubSpot's email. Instead, the import tool uses an XML external ID — a string of the form __import__.123 or your_module.contact_acme — stored in the id column on the import spreadsheet. The external ID is the upsert key: re-importing the same row with the same external ID updates; a new external ID creates ⁵.

If you do not supply external IDs, Odoo creates them automatically and you lose the ability to deterministically re-import. For native dedup on res.partner, install the Data Cleaning app and configure dedup rules on email, phone, or VAT number ¹². Custom field types determine validation and storage; the catalogue below covers what you can model and the limits you need to plan around ⁹.

Relationships in Odoo are modelled by relational fields with explicit ondelete semantics: cascade deletes children when the parent is deleted, restrict blocks the parent delete, set null clears the foreign key ¹⁵. This is configured in fields.py per field, not at the database level you can flip from the UI.

Custom Objects in Odoo are not a separate concept — they are simply new Python models, declared in a custom module's models/ folder, or created via Studio (Enterprise) which writes the same metadata into ir.model and ir.model.fields ¹⁶. Either way, the model must exist in the database before records of that type can be imported.

The single best predictor of a clean Odoo CRM migration is how much work you do on the source side before the first import button is pressed. Odoo's own implementation guide warns that data preparation — not the upload itself — is where most projects lose days, and the fix is almost always pre-processing rather than post-cleanup.

The single best predictor of a clean migration is how much work you do before the first import button is pressed.

Treat the source export as raw material that needs to be shaped to Odoo's expected formats — dates rewritten to YYYY-MM-DD (ISO-8601), selection values converted to their internal keys, Many2one relations resolved to either a name string or an external ID, owner emails resolved to existing res.users records, and every row stamped with a stable id column.

Source-side prep

• Audit and dedup the source database before export — Odoo's Data Cleaning app handles post-import dedup on res.partner, but it is much cheaper to dedup on the source than to merge after ¹². Match on email, phone, and VAT number.
• Normalise dates to YYYY-MM-DD or YYYY-MM-DD HH:MM:SS in UTC. Odoo's importer auto-detects most formats but warns that day/month inversions like 01-03-2016 are ambiguous; use ISO-8601 to remove the guesswork ¹³.
• Convert selection field labels to internal keys — for stage names, lead status, and any custom Selection field, Odoo expects the Python key (e.g. done, cancel), not the display label. Mismatches fail on import with cryptic errors ⁹.
• Stamp a stable external ID in an id column on every export row — a UUID, the source platform's primary key, or a namespaced string like legacy.contact_42. This is what makes re-runs and reconciliation deterministic ⁵.
• Decide what is in scope for historical activities. mail.activity and mail.message rows can be imported, but the chatter history from a separate CRM rarely preserves cleanly without custom scripting against the ORM.

Destination-side prep

• Create a staging database on Odoo.sh (staging branches are first-class) or a duplicate database on Odoo Online/on-prem to dry-run the import end-to-end. Restore a sanitised copy of production into staging weekly during the project.
• Provision users first under Settings → Users & Companies → Users, assigning each to the Sales/Salesperson groups and a crm.team. Owner assignment fails silently if the referenced user does not exist ²⁰.
• Pre-create every custom field on the right model via Studio (Enterprise) or Developer Mode → Settings → Technical → Fields (Community). Selection fields must have their full key list defined before any value is imported.
• Build pipelines, stages and teams in CRM → Configuration → Stages and Sales Teams before importing leads — rows targeting a non-existent stage_id fall back to the default stage rather than failing loudly.
• Install required modules first — Sales, CRM, Contacts, Discuss (for chatter), Calendar (for activities), and any community OCA modules you intend to depend on. Trying to import to a model whose module is not installed throws Model not found.

People prep

Cutover only works if humans cooperate. Lock down a source-system freeze window — typically 24 to 72 hours — and communicate it to every department that touches the CRM. Train sales reps on Odoo's kanban pipeline drag-and-drop, the chatter and activity widgets, and the Discuss inbox before go-live, not after.

A typical small-business migration runs one to two business days; a Salesforce-to-Odoo project with deal history, custom modules and Studio rebuilds runs two to four weeks of elapsed time even when the technical work is faster ²¹. Build the human runway accordingly.

Odoo exposes several load paths and the right one depends on dataset size, model mix, and whether you need to re-run idempotently. The UI Import wizard (powered by the base_import module) covers most one-shot migrations under a few hundred thousand records. Programmatic loads handle repeatable and very large volumes. Third-party tools sit on top of both and add staging, transformation and dedup layers.

UI Import wizard (base_import)

The native import lives on every model's list view: open the model (Contacts, Sales → Leads, etc.), click the Actions icon (or the gear menu in older versions), then Import records → Upload File ⁶. The wizard accepts CSV and Excel (XLSX) files, auto-detects column-to-field mapping by name, exposes a Show fields of relation fields (advanced) toggle to see related model fields, and offers a Test mode that validates the file without writing rows.

There is no hard daily row cap in base_import, but Odoo Online and Odoo.sh enforce per-instance memory and CPU limits that practically cap a single import at the low hundreds of thousands of rows before the worker times out ⁵. The right call: UI for one-shot loads under 100k records on standard models, or any time you want a visual mapping review and a Test pass before commit.

For Excel files, save as .xlsx (not .xls) — older formats are less reliable ⁵. Re-imports against the same external ID in the id column update existing rows; new external IDs create.

Programmatic loads — XML-RPC and JSON-RPC transports

Odoo's programmatic load surface has existed since version 6 and exposes the same ORM methods as the UI ²². Calls invoke execute_kw(db, uid, password, model, method, args) with methods like create, write, search_read, and the bulk-friendly load.

The load() method is what base_import calls internally — it accepts a list of field names and a list of value rows and applies the same external-ID upsert semantics as the UI wizard. For bulk loads, batch records into chunks of 100 to 500 per create or load call; smaller batches add round-trip overhead, larger batches risk request timeouts on Odoo.sh.

Choose the programmatic path when the load is over 100k records, when custom models are involved, when the migration needs to be repeatable and audit-logged from your side, or when you are syncing from an external warehouse. Wrap calls in a back-off loop on throttle and connection-reset errors.

Third-party staging tools and OpenUpgrade

Tools like Fivetran, Airbyte and Stacksync ship Odoo connectors that sit between the source and the destination. They are commonly used in two ways: (a) reverse-ETL where the source database is loaded into a warehouse, transformed in SQL, then synced into Odoo via XML-RPC; and (b) staging-and-validate, where the tool generates the import CSV, runs type coercion, and feeds the result to the wizard.

For Odoo-version migrations specifically (Community 15 → 18, etc.), the Odoo Community Association's OpenUpgrade project provides the only working open-source upgrade scripts for Community editions ²³. For Odoo Enterprise upgrades, Odoo S.A.'s paid upgrade service handles the schema transformation but is not available to Community users.

Mapping is where every migration earns its scars. The schema decisions you make in your mapping spreadsheet determine whether reports work on day two, whether automated actions fire correctly on day five, and whether your sales team trusts the data on day thirty.

Work model by model, top to bottom of the dependency order: res.users first (so owners can be referenced), then companies on res.partner (so contacts and leads can associate to them), then individual contacts on res.partner, then crm.lead, then mail.activity and mail.message, then sale.order if you are bringing in quote history.

Contacts (res.partner)

Companies and parent-child relations

Odoo collapses companies and contacts into the same res.partner table, distinguished by the is_company boolean and linked through parent_id. The clean import order is: companies first with is_company=True and stable external IDs, then individual contacts with is_company=False and parent_id/id pointing to the company's external ID ¹¹.

If you are consolidating multiple source systems, run each through a transform step that adds a system prefix to the external ID (hubspot.contact_123, pipedrive.contact_456) so you can re-import deltas from either system without collision.

Leads, opportunities and pipelines (crm.lead, crm.stage)

crm.lead is the single table for both leads and opportunities — the type field stores 'lead' or 'opportunity', and conversion is a state transition rather than a record move. Recreate every pipeline and every stage in CRM → Configuration → Stages before importing — rows referencing a non-existent stage_id will be ignored or fall to the default stage.

If you are consolidating multiple source pipelines into Odoo, the cleanest approach is to keep them as separate sales teams (crm.team) with their own stages for at least 90 days post-migration, then merge once reporting has stabilised.

Custom-field mapping strategy

Resist the urge to map every source custom field one-to-one. Migrate only the custom fields used by an active process, automated action, or report in the last 12 months. Excess fields weaken governance, slow down list views, and make the model harder to upgrade between Odoo versions because every custom field has to round-trip through OpenUpgrade or the paid upgrade service ²³.

For Selection fields whose source values do not match the destination, either: (1) extend the destination Selection with the missing internal keys via Studio or fields.py, (2) collapse adjacent values during transform, or (3) introduce a parallel legacy_value Char field that holds the source value verbatim. Computed fields (Odoo decorator-based or compute=) do not import — Odoo recomputes them on save — so any source formula must be rebuilt as a computed field on the model or replicated via Server Actions.

Historical activities, notes and chatter

Odoo splits historical engagement across three tables: mail.activity (scheduled to-dos with a date_deadline), mail.message (chatter messages and emails attached to a record), and calendar.event (meetings synced from Outlook/Google) ²⁵. mail.message is what shows in the chatter widget on every record's right side, and it is the destination for migrated email and call history ²⁶.

Bulk-importing historical chatter is non-trivial because mail.message enforces strict relations on model, res_id, author_id and threading via parent_id. The Odoo forum's general guidance is that note, message and activity history *can* be imported via the export/import feature, but typically requires a Python script against the ORM to handle threading and author resolution correctly ²⁷.

For one-off imports under a few thousand messages, CSV via the wizard works; above that, script against mail.message.create with explicit model='crm.lead' and res_id set to the lead's database ID.

Activities (calls, meetings, to-dos) can be created with a backdated date_deadline and summary, but create_date on the activity itself cannot be overridden — it stamps to import day ²⁸. If you need a historical timeline view, store the original timestamp in a custom legacy_date Datetime field on the activity and filter reports off that.

Files and attachments

Attachments in Odoo live on the ir.attachment model and link to any record via res_model and res_id. Default per-attachment size cap is 128 MiB and cannot be increased in Odoo Online; self-hosted instances can raise it in server configuration ¹⁴. Supported image formats include JPEG, PNG, GIF, BMP, TIFF, SVG, ICO, WEBP, PSD and EPS ²⁹.

Bulk attachment import is not part of base_import — the supported path is either (a) the Documents app (Enterprise) which exposes a drag-and-drop bulk uploader, (b) the fs_attachment OCA module which moves the filestore to S3 or an external filesystem ³⁰, or (c) scripted upload via the ORM where you base64-encode the binary and create an ir.attachment record with datas, name, res_model and res_id set.

For large attachment estates, most teams adopt: keep originals in S3, install fs_attachment, and only inline-upload the most recent or most-referenced subset.

Audit trail, ownership and original timestamps

Odoo records create_date, create_uid, write_date and write_uid automatically on every model and does not preserve the original file's creation or modification date during import — create_date stamps to upload time ²⁸. If you need to preserve the original audit trail, create two custom fields per model — legacy_create_date (Datetime) and legacy_create_uid (Many2one to res.users) — and populate them from the source export.

Owner assignment during import works only if the res.users record exists at the moment of import; rows whose user_id cannot be resolved import with no owner set, which silently breaks team-based record rules and pipeline routing ²⁰.

Account-level audit logging is not on by default. The OCA Audit Log module lets you define per-model rules in Settings → Technical → Audit → Rules and writes old/new values for every change ³¹. Without it (or the Enterprise Audit Trail in the Accounting app), there is no out-of-the-box per-field change history.

CRM-specific: lead scoring, email/calendar sync, automated actions

Lead-scoring rules do not import — they are rebuilt in CRM → Configuration → Lead Scoring Rules (Enterprise) or via custom server actions on Community. Plan to recreate the rule logic from your source platform documentation rather than trying to migrate accumulated score values; if you must preserve historical scores, store them in a legacy_score Float field and let the new rules accrue forward.

Email and calendar sync is configured per user under Settings → General Settings → Discuss / Calendar for Outlook (requires an Azure AD App Registration with Application ID and Client Secret) and Google Workspace ³². Set this up *after* user provisioning is complete but *before* the activity import runs, or you risk duplicate calendar entries when the connector backfills against the same events you are loading.

Automated Actions (the Odoo equivalent of HubSpot workflows) and Server Actions are stored in base.automation and ir.actions.server and do not move with a CSV import — they are rebuilt in the destination by an admin in Settings → Technical → Automation Rules.

Validation is the bridge between the import finishing and users being allowed in. Odoo implementation guides recommend a three-stage validation: a test load of 10 percent of records with stakeholder spot-checks, the full load with real-time monitoring of record counts and relation integrity, and a 30-day post-migration data-quality audit. The most reliable signal is having department reps verify their own records — they know what right looks like better than any reconciliation script.

Build a reconciliation queries spreadsheet that compares source and destination on each of these counts. Anything outside a 0.5 percent variance gets investigated before users get login access.

• Total partners imported vs source — split by is_company True/False — minus deliberately excluded rows (role-based emails, bounced lists, opt-outs).
• Total leads and opportunities per stage per team vs source, plus sum of expected_revenue per pipeline — a non-trivial revenue variance usually signals a stage-mapping error or a currency-precision drop.
• Activities and messages per record — count mail.activity and mail.message rows against source-derived expectations, and confirm date_deadline and legacy_create_date round-tripped.
• Parent-child integrity on res.partner — every contact with is_company=False should have a parent_id pointing to a valid is_company=True partner; orphans indicate a broken company-first import.
• Owner distribution — GROUP BY user_id on crm.lead and confirm no lead landed unowned that should not have.
• External-ID uniqueness — query ir.model.data for duplicate (module, name) combinations on your namespace; any duplicates indicate the dedup transform missed cases.
• Attachment counts per record — for migrated ir.attachment rows, count by res_model and compare against the source file inventory.

On top of reconciliation, run a manual spot-check protocol: pick 30 random records across models and verify each field against the source UI. Pick five high-value opportunities and trace the full relation graph — partner, sales team, owner, activities, chatter, attachments, related quotes. If a non-trivial discrepancy shows up in three or more of the 30, halt the load, fix the root cause, and re-import the affected rows by external ID.

Odoo does not ship a native bulk-undo. The closest thing is the OCA Audit Log module (when enabled with the right rules) which captures old/new values per change ³¹, plus the Odoo.sh staging branches feature which lets you fork production and roll back at the database level. Neither is a one-click reversal — both depend on having set them up *before* the import.

The real rollback strategy remains: take a full PostgreSQL backup via /web/database/manager (pg_dump -Fc plus the filestore directory) before the import starts, stamp every imported row with a custom import_batch_id Char field, and if catastrophe strikes, archive-by-batch and re-import from the cleaned source.

Cutover sequencing: (1) source goes read-only and the team is notified; (2) final delta export captures everything that changed during the test-import window; (3) delta is imported with the same external-ID namespace; (4) reconciliation runs; (5) users get login access and a 48-hour hyper-care window with the migration lead on call; (6) source decommission is scheduled for 30 to 90 days out, never the same day.

Odoo S.A. runs a tiered partner programme — Gold, Silver and Ready — based on certifications, customer count and recurring Enterprise revenue. For CRM migrations specifically, partners with explicit Salesforce-to-Odoo, Zoho-to-Odoo or Pipeline-CRM-to-Odoo practices tend to ship cleaner than generalist implementation shops ²¹. The Odoo Community Association (OCA) maintains open-source modules — Audit Log, OpenUpgrade, fs_attachment, Data Cleaning OCA forks — that fill gaps left by the Enterprise feature set ²³³¹.

Synavos, Aspire Softserv, Silent Infotech, Iqra Technology, Softeko, Braincuber and ECOSIRE are commonly named in the migration corner of the market and each offers fixed-scope or hourly-rate migration packages alongside ongoing managed services ³⁹. Odoo S.A. also runs a paid upgrade service for Enterprise customers, which handles version-to-version schema migration but is not available to Community users — for Community, OpenUpgrade is the working alternative ²³.

On the ETL and iPaaS side, Fivetran, Airbyte and Stacksync ship Odoo connectors, and several Odoo Apps Store extensions (Import Bridge by Axis, base_import_async by OCA) add async-job patterns on top of the wizard.

Their role in a migration is rarely the migration itself — it is the staging layer that lands source data into a warehouse, the transformation layer that converts Selection values and resolves Many2one relations, and the ongoing-sync layer that takes over once the one-time migration is complete.

Managed-migration cost ranges vary widely. Hourly rates for Odoo professional services run $10–$150+ per hour depending on region and partner expertise. A clean Pipeline-CRM-to-Odoo move of under 25,000 contacts with no historical chatter and standard models only often lands in the $3,000–$10,000 range.

A Salesforce-to-Odoo project with opportunity history, Studio customisations, historical activities and Marketing-Automation decoupling typically runs $20,000–$150,000+, with the upper end driven by record count, custom-model complexity, historical-data depth, and the number of integrations that need rebuilding rather than re-pointed ³⁹.

Migration-platform tools that scope by record-count tier (free under 100 records, $149 under 5,000, $599 under 25,000, $2,499 under 500,000) sit at the lower end of the curve when the migration is simple and standard-object-only. The price climbs sharply once custom models, historical activities or chatter migration enter scope.

For teams that want to outsource the migration end-to-end, FlitStack specialises in Odoo CRM migrations and handles the external-ID design, Selection-key conversion, res.partner parent-child resolution, historical-data preservation and validation work described in Sections 5 and 7 of this guide. Pricing is fixed-fee, based on record count and source platform, with separate line items for custom models and historical chatter depth so the scope is transparent before signature.

This is one of several legitimate paths — the right choice for any given team depends on whether they want an Odoo Gold Partner, the paid Odoo upgrade service, an iPaaS-first approach, an OCA-and-OpenUpgrade route, or a specialist migration vendor. Explore FlitStack →