Field mapping

​

How field mapping works

At the Mapping step of the import wizard, Qwoty lists each header of your file (Your file header) and the field it maps to (Maps to).

​

Automatic mapping

Qwoty matches a column automatically when its header is the exact column name from the template (for example inventory[sku]) or a known alias (for example sku, api_name, description). Partial matches are never used, so parent_product_name doesn’t map to product_name. Product custom field columns named custom[<api_name>] are matched automatically when the API name exists in your data model.

​

Manual mapping

For each column, you can:

• Map it to a field: pick a field in the Maps to list (fields are grouped, for example Main information, Settings, Shipping)
• Ignore this column: the column isn’t imported

Required columns are marked. You can’t continue until they’re all mapped. Each Qwoty field accepts only one source column.

​

Data format requirements

Download the template from the import screen before preparing your file: it shows the expected syntax for each column.

​

Text fields

• No special formatting required
• If a value contains a comma, line break, or quote, wrap the cell in double quotes: "Premium, Extra Large"

​

Number fields

• Numbers only
• Decimals use a period: 1234.56
• No thousands separators (not 1,234.56)
• Percentages are numbers between 0 and 100 (8.95 = 8.95%)

​

Boolean fields

Use true or false, for fields like settings[is_active] and pay_as_you_go.

​

Date fields

For date custom fields, use ISO 8601: YYYY-MM-DD, for example 2026-04-25.

​

Tax fields

vat_code takes the API name of a tax from Settings › Workspace › Tax (for example FR_200).

​

Enum (select) fields

​

Multi-value fields

Some fields accept several values in one cell, separated by commas, with the cell wrapped in double quotes:

​

Indexed fields (tiers, options)

​

ID fields

• Products: product_id is optional. Leave it empty to create a product, or set the UUID of an existing variant to update it.
• Prices: id is required. It takes the price UUID or a price key (product_api_name.pricebook_api_name, plus .period_unit.period for recurring prices).

UUIDs look like c776ee49-f608-4a77-8cc8-6fe96ae1e43f.

​

Relation fields

To link records to catalogs, categories, or option values, see Import relations.

​

Finding API names

Catalog, category, pricebook, and variant option references use API names, not display labels. You find them:

• On each record’s page in Products & pricing (Catalog, Pricebook, Product options)
• In an export: the product and price exports include catalog_api_names, category_api_names, product_api_name, and pricebook_api_name

​

Related