> ## 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.
# Prepare your CSV files
> Complete step-by-step guide to format your data for import into Qwoty.
This guide walks you through preparing your CSV file for a successful import into Qwoty. Follow these steps in order to avoid errors.
## Step 1: Check file requirements
Before you start, ensure your file meets these requirements:
| Requirement | Details |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| **Format** | CSV |
| **Encoding** | UTF-8 (recommended) |
| **Field separator** | Comma `,` |
| **Decimal separator** | Period `.` |
| **Within-cell separator** | Comma `,` separates multiple values inside a single cell (for example, multiple catalog API names) |
| **Structure** | One object type per file (Master products, Products, or Prices) |
| **First row** | Headers — every column must have a name |
For datasets larger than 10,000 rows, split into multiple files or use the [Qwoty API](https://docs.qwoty.io).
## Step 2: Download the sample file
**This is the most important step.** The sample file shows you the exact column names and format Qwoty expects.
1. Open **Settings → Data → Import/Export Data**.
2. Select the object you want to import: **Master products**, **Products**, or **Prices**.
3. Click **Download example file**.
4. Use this file as your template — keep the headers, replace the example rows with your data.
**Pro tip:** export a few existing records first instead of starting from the
empty template. The export gives you real examples of how Qwoty formats data,
and the column names map automatically when you re-import.
## Step 3: Remove duplicate values
Qwoty enforces uniqueness on certain fields. Duplicates cause import errors.
| Object | Unique fields |
| ------------------- | -------------------------------------------------------------------------- |
| **Master products** | `product_parent_id`, `parent_product_api_name` |
| **Products** | `product_id`, `product_api_name`, `inventory[sku]` (if used as identifier) |
| **Prices** | `id` |
Before importing:
1. Sort your spreadsheet by the unique field.
2. Remove or merge duplicate rows.
3. Check for duplicates that already exist in Qwoty by exporting first.
## Step 4: Format each field type correctly
Different field types require specific formats. Here's the complete reference for Qwoty.
### Text fields
* No special formatting required.
* Leading and trailing spaces are automatically trimmed.
* If a value contains a comma, line break, or quote, wrap it in double quotes: `"Premium, Extra Large"`.
### Number fields
* Numbers only (no text).
* Use period for decimals: `1234.56`.
* No thousands separators (not `1,234.56`).
* Negative numbers allowed only where the schema permits (most price fields require positive values).
### Boolean fields
Use lowercase: `true` or `false`.
This applies to fields like `settings[is_active]`.
### 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 different from `Flat`. `recurring` is
different from `Recurring`. Use the exact values shown above.
### Date fields
Use ISO 8601:
* `YYYY-MM-DD` — 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` — not the symbol (`€`, `$`) or the full name.
### Tax (VAT) fields
Use the format `_`. Examples:
| Value | Meaning |
| -------- | ------------------ |
| `FR_200` | France, 20.0% VAT |
| `FR_055` | France, 5.5% VAT |
| `DE_190` | Germany, 19.0% VAT |
| `-` | No tax |
### ID fields
* **Optional**: Qwoty auto-generates UUIDs if not provided.
* **Format**: UUID, for example `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`.
* **Use case**: Include the ID to **update** existing records instead of creating new ones.
### Multi-value fields
Some fields accept multiple values inside a single cell, separated by **commas**:
| Column | Example |
| -------------------- | ------------------------ |
| `catalog_api_names` | `france,partner_pricing` |
| `category_api_names` | `hardware,accessories` |
If a value within the list contains a comma, wrap the whole cell in double quotes: `"category_one,category, with comma"`.
### Indexed fields (tiers, options)
Qwoty uses bracket notation with a numeric index for repeating field groups. Indexes are **0-based** for tiers and **1-based** for options.
```text theme={null}
tiers[starting_unit][0],tiers[ending_unit][0],tiers[price][0]
options[1][name],options[1][value]
```
Add `[1]`, `[2]`, `[3]`... to declare additional rows.
## Step 5: Add relation columns
Qwoty objects reference each other through specific fields. To link a record to its parent or related object, populate the right column.
| Linking | Column to populate |
| ------------------------ | ------------------------------------------------------------------- |
| Product → Master product | `parent_product_api_name` (preferred) or `product_parent_id` (UUID) |
| Product → Catalog(s) | `catalog_api_names` (comma-separated) |
| Product → Category(ies) | `category_api_names` (comma-separated) |
| Price → Product | `product_id` (UUID) |
| Price → Pricebook | `pricebook_id` (UUID or pricebook name) |
**Import order matters!**
1. **Master products** first — they're the parents.
2. **Products** second — they reference master products.
3. **Prices** last — they reference both products and pricebooks.
Catalogs, Categories, and Pricebooks must exist before you start. Create them through the UI first.
## Step 6: Ensure custom fields exist in Qwoty
The import creates **records**, not **fields**. Any custom field you want to populate must already exist in your data model.
Before importing:
1. Open **Settings → Data → Data model**.
2. Select the object (Customer, Contract Model — note that Products and Prices are not currently extensible with custom fields).
3. Add the custom fields you need.
4. Make sure the column header in your CSV matches the field's API name exactly.
See the [Data model](/user-guide/data-model/introduction) page for the full guide on adding custom fields.
## Step 7: Final checklist
Before uploading your file, verify:
* File is in **CSV** format
* Encoding is **UTF-8**
* Field separator is **comma `,`**
* Decimal separator is **period `.`**
* Multi-value cells use commas inside, with quotes around the cell if needed
* No duplicate values in unique fields (`product_id`, `product_api_name`, `id`)
* Boolean fields use **lowercase** `true` or `false`
* Enum fields use the **exact case** shown in Step 4
* Dates use **ISO 8601** format
* All custom fields exist in **Settings → Data → Data model**
* Master products are imported **before** products
* Products are imported **before** prices
* Catalogs, Categories, and Pricebooks already exist in the workspace
## Common mistakes to avoid
| Mistake | Solution |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Using `;` as the separator | Qwoty expects comma `,` |
| Using `flat` or `recurring` (lowercase) for `pricing_model` | Use `Flat`, `Volume Tiered`, etc. — exact case |
| Importing products before their master | Always import master products first |
| Forgetting to wrap multi-catalog values in quotes | `"france,partner_pricing"` is required when the cell contains commas |
| Mapping the same column twice | Each Qwoty target accepts only one source column |
| Using `,` as the decimal separator | Numbers must use period `.` |
| Mixing `recurring` (product) with `one-time` (price) | `settings[recurrence_type] = recurring` requires `type = reccuring` on the price |
## Next steps
Your file is ready. Now:
Always start here.
Once your masters exist.
Last step — prices reference products and pricebooks.
Add custom fields before importing if needed.