> ## 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.
# Import relations between objects
> Import relationships between products, masters, prices, catalogs, and pricebooks via CSV.
## Overview
Qwoty supports importing relationships between objects during CSV import. This lets you link records (for example, attach products to a master, or attach prices to a pricebook) as part of your data migration.
**Supported relations for import:**
* **Product → Master product** (parent/child)
* **Product → Catalog** (one product attached to one or more catalogs)
* **Product → Category** (one product attached to one or more categories)
* **Price → Product** (each price targets one product)
* **Price → Pricebook** (each price belongs to one pricebook)
## How relations work in Qwoty
### One-to-many relations
Qwoty's catalog model uses standard one-to-many relations:
* **One Master product → Many Products (variants)** — a master groups several variants
* **One Pricebook → Many Prices** — a pricebook is the container for prices across products
* **One Catalog → Many Products** — a catalog scopes which products are sellable in a market or segment
### Many-to-many relations
Some relations are many-to-many — these use comma-separated lists inside a single CSV cell, with the cell wrapped in double quotes:
| Relation | CSV column | Example |
| -------------------- | -------------------- | -------------------------- |
| Product ↔ Catalogs | `catalog_api_names` | `"france,partner_pricing"` |
| Product ↔ Categories | `category_api_names` | `"hardware,accessories"` |
## Linking records during import
### Step 1: Identify the "one" and "many" sides
For each relation, determine which side is the parent ("one") and which is the child ("many"):
| Relation | "One" side | "Many" side |
| ----------------- | -------------- | ----------------- |
| Master / Variant | Master product | Product (variant) |
| Pricebook / Price | Pricebook | Price |
| Catalog / Product | Catalog | Product |
| Product / Price | Product | Price |
### Step 2: Ensure the "one" side records exist
Before importing the "many" side, the "one" side records must already exist in Qwoty.
* Create your **Catalogs**, **Categories**, and **Pricebooks** through the UI first
* Import **Master products** before importing their variants
* Import **Products** before importing their prices
The import will fail if a row references a record that doesn't exist.
### Step 3: Prepare your CSV file
Add a column in your "many" side CSV file that references the "one" side using a unique identifier:
| Linking | Column to populate | Accepted format |
| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------ |
| Product → Master | `parent_product_api_name` (preferred) or `product_parent_id` | API name (Text) or UUID |
| Product → Catalog(s) | `catalog_api_names` | Comma-separated API names, in quotes if multiple |
| Product → Category(ies) | `category_api_names` | Comma-separated API names, in quotes if multiple |
| Price → Product | `product_id` | UUID |
| Price → Pricebook | `pricebook_id` | UUID or pricebook name |
The reference value must **exactly match** the unique field on the parent record. For API names, this means the same case, no extra spaces, no extra characters. Verify the parent's API name in **Settings → Data → Data model** or in the parent object's list view.
### Step 4: Ensure the relation field is populated correctly
Before uploading your file, double-check that:
* The parent records have the API names or UUIDs you reference
* The `*_api_names` columns use commas (not semicolons) inside the cell, with double quotes around multi-value cells
* The `parent_product_api_name` column matches your master's API name byte-for-byte
### Step 5: Upload and map the relation
1. Upload your CSV file via the import UI
2. In the **Mapping** step, find your relation column (for example, `catalog_api_names`)
3. Map it to the matching Qwoty field (for example, **Catalog API Names**)
4. Qwoty automatically links each record to the matching parent at the **Confirm** step
## Available unique fields for relations
| Object | Unique fields available for references |
| -------------------------------------------- | -------------------------------------------------- |
| **Master products** | `product_id` (UUID), `product_api_name` |
| **Products** | `product_id` (UUID), `product_api_name` |
| **Catalogs** | API name (set when the catalog is created) |
| **Categories** | API name |
| **Pricebooks** | UUID or pricebook name |
| **Customers** (when migrating customer data) | `id`, custom unique fields you've marked as unique |
We recommend using API names (`parent_product_api_name`, `catalog_api_names`, `category_api_names`) when possible — they're human-readable, easy to maintain in spreadsheets, and survive across environments.
## Import order rule
**Always import the "one" side first.**
1. **Catalogs, Categories, Pricebooks** — must exist in your workspace before any import (create them through the UI).
2. **Master products** — import these first. They're the parents that variants reference.
3. **Products** — import second, referencing their masters.
4. **Prices** — import last, referencing both products and pricebooks.
The parent record must exist before you can reference it. The import fails for rows pointing to records that don't yet exist.
## Related
Which fields are unique and what that means for relations.
Format requirements for relation columns.
Always start your migration here.
Final step — references products and pricebooks.