Importing

---
name: importing
description: Load data into Odoo from CSV, Excel, or external systems — idempotently via external IDs. Use when the user wants to bulk-import contacts, products, leads, transactions, or any other records.
triggers: [import, load, bulk, csv, excel, xlsx, upload, migrate, seed]
---

# Importing

Bring external data in without creating duplicates on re-runs.

## Core pattern: idempotent import

Use `import_records` with `__import__.external_id` on every row:

- First run → records get created
- Second run with same external_id → updates existing records
- No duplicates, no manual cleanup

External ID format: `__import__.your_stable_key` (e.g. `__import__.contact_12345`)

## Typical workflows

1. **Map fields first** — list source columns → Odoo model fields via `list_models` then introspect
2. **Resolve references upfront** — m2o fields (e.g. `country_id`) need IDs or external IDs, not names
3. **Dry-run small batch** — import 5 rows, inspect, then scale
4. **Batch size** — 500-1000 rows per call is the sweet spot
5. **Retry on fail** — fix source rows, re-run with same external_ids to patch

## Choosing the right tool

- `import_records` — best for CSV-shaped data, handles external IDs natively
- `create_records` — direct writes, no external ID mapping
- `update_records` — when you already have internal IDs

## Gotchas

- m2o by name is fuzzy and unsafe for non-unique names — always resolve to ID or external ID first.
- Boolean fields accept `1/0` or `True/False` — be consistent per column.
- Dates must be ISO `YYYY-MM-DD`; datetimes `YYYY-MM-DD HH:MM:SS` UTC.
- `product.product` vs `product.template`: if you import variants, hit `product.product` and set `product_tmpl_id`.
- Currency / decimal separators: Odoo expects `.` as decimal, regardless of locale.