Skip to main content
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: 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.
  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. 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:
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 <COUNTRY_CODE>_<RATE>. Examples:

​
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: 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.
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.
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 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

​
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.