Skip to main content

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.

​
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:
RelationCSV columnExample
Product ↔ Catalogscatalog_api_names"france,partner_pricing"
Product ↔ Categoriescategory_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 / VariantMaster productProduct (variant)
Pricebook / PricePricebookPrice
Catalog / ProductCatalogProduct
Product / PriceProductPrice

​
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:
LinkingColumn to populateAccepted format
Product → Masterparent_product_api_name (preferred) or product_parent_idAPI name (Text) or UUID
Product → Catalog(s)catalog_api_namesComma-separated API names, in quotes if multiple
Product → Category(ies)category_api_namesComma-separated API names, in quotes if multiple
Price → Productproduct_idUUID
Price → Pricebookpricebook_idUUID 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

ObjectUnique fields available for references
Master productsproduct_id (UUID), product_api_name
Productsproduct_id (UUID), product_api_name
CatalogsAPI name (set when the catalog is created)
CategoriesAPI name
PricebooksUUID 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.

Uniqueness constraints

Which fields are unique and what that means for relations.

Field mapping

Format requirements for relation columns.

Import master products

Always start your migration here.

Import prices

Final step — references products and pricebooks.