> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwoty.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Field mapping
> How field mapping works during data import in Qwoty.
## How field mapping works
When you upload a CSV file, Qwoty analyzes your columns and attempts to match them to existing fields on the target object.
### Automatic mapping
Qwoty tries to match columns based on:
* Column header names (exact or similar matches to Qwoty's field names)
* Data type detection (UUIDs, numbers, booleans, ISO dates)
* Common field patterns
**Quick tip:** export a few rows from the object you want to import. The exported file will have the exact column names Qwoty expects, making automatic mapping seamless during import.
### Manual mapping options
For each column, you can:
* **Map to a field** — select the matching Qwoty field from a dropdown at the **Mapping** step
* **Ignore this column** — skip the column entirely (data won't be imported)
**Fields must exist before import.** The import creates records, not fields. Create custom fields under **Settings → Data → Data model** before importing. See the [Data model](/user-guide/data-model/introduction) page for details.
## Field type compatibility
All field types available in Qwoty's data model are supported for import. You can also import `id` (or `product_id`, depending on the object) values to either assign a specific UUID to new records or update existing ones.
## Data format requirements
Some fields have special syntax. We recommend downloading the **example file** from the import screen before preparing your import — it shows the expected syntax for each field type.
### Text fields
* No special formatting required
* Leading and trailing spaces are trimmed automatically
* If a value contains a comma, line break, or quote, wrap the cell in double quotes: `"Premium, Extra Large"`
### Number fields
* Numbers only
* Decimals use a period: `1234.56`
* No thousands separators (not `1,234.56`)
* Negative numbers are accepted only where the field permits (most price fields require positive values)
### Boolean fields
Use lowercase `true` or `false` — applies to fields like `settings[is_active]`.
### Date fields
Use ISO 8601:
* `YYYY-MM-DD` (recommended) — for example, `2026-04-25`
* `YYYY-MM-DDTHH:MM:SSZ` for timestamps
### Currency fields
Use the ISO 4217 three-letter code: `EUR`, `USD`, `GBP`, `JPY`. Don't use the symbol (`€`, `$`) or the full name.
### Tax (VAT) fields
Use the format `_` where the rate is expressed without a decimal point (multiply by 10):
| Value | Meaning |
| -------- | ------------------ |
| `FR_200` | France, 20.0% VAT |
| `FR_055` | France, 5.5% VAT |
| `DE_190` | Germany, 19.0% VAT |
| `-` | No tax applied |
### Enum (select) fields
Use the **exact value** Qwoty expects, including capitalization. Common enums:
| Field | Accepted values |
| --------------------------- | ---------------------------------------------------------------------------- |
| `settings[recurrence_type]` | `one_off`, `recurring` |
| `settings[product_type]` | `physical`, `service`, `subscription` |
| `type` (price) | `one-time`, `reccuring` |
| `pricing_model` | `Flat`, `Cost based`, `Percent`, `Graduated Tiered`, `Volume Tiered`, `None` |
| `period_unit` | `day`, `week`, `month`, `year` |
Enums are **case-sensitive**. `flat` is rejected — use `Flat`. `Recurring` is rejected — use `recurring`. Use the exact values shown above.
### Multi-value fields
Some fields accept multiple values inside a single cell, separated by **commas**, with the cell wrapped in double quotes:
| Column | Example |
| -------------------- | -------------------------- |
| `catalog_api_names` | `"france,partner_pricing"` |
| `category_api_names` | `"hardware,accessories"` |
### Indexed fields (tiers, options, identifiers)
Qwoty uses bracket notation with a numeric index for repeating field groups. Two conventions coexist depending on the object:
| Pattern | Index base | Example |
| --------------- | ---------- | -------------------------------------------------------------- |
| Product options | 1-based | `options[1][name]`, `options[1][value]`, `options[2][name]`... |
| Price tiers | 0-based | `tiers[starting_unit][0]`, `tiers[starting_unit][1]`... |
Add `[1]`, `[2]`... or `[0]`, `[1]`... depending on the field group to declare additional rows.
### ID fields
Specifying an ID during import is optional. Qwoty auto-generates a UUID if not provided.
Use cases for mapping an ID column:
* **Set a specific ID** — choose the UUID for newly created records
* **Update existing records** — match against existing records to update them instead of creating duplicates. In that case, only map the ID column — don't combine it with other unique fields, to keep the import simple.
If you provide an ID, it must be in UUID format (for example, `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`).
### Relation fields
For linking records to their parent or related object, see the [Import relations](/user-guide/data-migration/reference/import-relations) page.
## Finding API names
For Catalog, Category, and Pricebook references, you must use the **API name** (not the display label).
### How to find API names
1. Open **Settings → Data → Data model**
2. Select the object (Catalog, Category, Pricebook)
3. View the API name shown in the **API Name** column
You can also export the object first — the exported CSV includes API names in the appropriate columns.
## Related
Supported file formats and CSV best practices.
Which fields are unique and how Qwoty enforces uniqueness.
How to link records to their parents during import.
Validation errors and how to fix them.