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.
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 .
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.
Open Settings → Data → Import/Export Data .
Select the object you want to import: Master products , Products , or Prices .
Click Download example file .
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_nameProducts product_id, product_api_name, inventory[sku] (if used as identifier)Prices id
Before importing:
Sort your spreadsheet by the unique field.
Remove or merge duplicate rows.
Check for duplicates that already exist in Qwoty by exporting first.
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, recurringsettings[product_type]physical, service, subscriptiontype (price)one-time, reccuringpricing_modelFlat, Cost based, Percent, Graduated Tiered, Volume Tiered, Noneperiod_unitday, 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-25YYYY-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 <COUNTRY_CODE>_<RATE>. Examples:
Value Meaning FR_200France, 20.0% VAT FR_055France, 5.5% VAT DE_190Germany, 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_namesfrance,partner_pricingcategory_api_nameshardware,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.
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!
Master products first — they’re the parents.Products second — they reference master products.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:
Open Settings → Data → Data model .
Select the object (Customer, Contract Model — note that Products and Prices are not currently extensible with custom fields).
Add the custom fields you need.
Make sure the column header in your CSV matches the field’s API name exactly.
See the Data model 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 commasMapping 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:
Import master products Always start here.
Import products Once your masters exist.
Import prices Last step — prices reference products and pricebooks.
Data model Add custom fields before importing if needed.
