Field mapping

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.

​

How field mapping works

When you upload a CSV file, Qwoty analyzes your columns and attempts to match them to existing fields on the target object.

​

Automatic mapping

Qwoty tries to match columns based on:

• Column header names (exact or similar matches to Qwoty’s field names)
• Data type detection (UUIDs, numbers, booleans, ISO dates)
• Common field patterns

​

Manual mapping options

For each column, you can:

• Map to a field — select the matching Qwoty field from a dropdown at the Mapping step
• Ignore this column — skip the column entirely (data won’t be imported)

​

Field type compatibility

All field types available in Qwoty’s data model are supported for import. You can also import id (or product_id, depending on the object) values to either assign a specific UUID to new records or update existing ones.

​

Data format requirements

Some fields have special syntax. We recommend downloading the example file from the import screen before preparing your import — it shows the expected syntax for each field type.

​

Text fields

• No special formatting required
• Leading and trailing spaces are trimmed automatically
• 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)
• Negative numbers are accepted only where the field permits (most price fields require positive values)

​

Boolean fields

Use lowercase true or false — applies to fields like settings[is_active].

​

Date fields

Use ISO 8601:

• YYYY-MM-DD (recommended) — 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. Don’t use the symbol (€, $) or the full name.

​

Tax (VAT) fields

Use the format <COUNTRY>_<RATE> where the rate is expressed without a decimal point (multiply by 10):

​

Enum (select) fields

Use the exact value Qwoty expects, including capitalization. Common enums:

​

Multi-value fields

Some fields accept multiple values inside a single cell, separated by commas, with the cell wrapped in double quotes:

​

Indexed fields (tiers, options, identifiers)

Qwoty uses bracket notation with a numeric index for repeating field groups. Two conventions coexist depending on the object: Add [1], [2]… or [0], [1]… depending on the field group to declare additional rows.

​

ID fields

Specifying an ID during import is optional. Qwoty auto-generates a UUID if not provided. Use cases for mapping an ID column:

• Set a specific ID — choose the UUID for newly created records
• Update existing records — match against existing records to update them instead of creating duplicates. In that case, only map the ID column — don’t combine it with other unique fields, to keep the import simple.

If you provide an ID, it must be in UUID format (for example, c776ee49-f608-4a77-8cc8-6fe96ae1e43f).

​

Relation fields

For linking records to their parent or related object, see the Import relations page.

​

Finding API names

For Catalog, Category, and Pricebook references, you must use the API name (not the display label).

​

How to find API names

1. Open Settings → Data → Data model
2. Select the object (Catalog, Category, Pricebook)
3. View the API name shown in the API Name column

You can also export the object first — the exported CSV includes API names in the appropriate columns.

​

Related