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.

A master product is the parent that groups multiple variants — for example, a “Premium T-Shirt” master with Small, Medium, Large variants. Always import master products before their variants and prices, since they’re the parent that everything else references.
You must have the Admin role with Data → Import CSV authorized. See Manage roles for permission details.

​
Open the import

1

Open Settings

In the left sidebar, click Settings.
2

Navigate to Import/Export Data

Under the Data section, click Import/Export.
3

Select Master products

Tick the Master products card at the top of the page. The Import and Export sections below adapt.
4

Click Download example file

Get the sample CSV with the right column headers.
5

Click Import

Drop your prepared file. The 4-step wizard runs: Upload → Mapping → Confirm → Result.

​
CSV columns reference

The Master products import uses the same template as Products — the difference is in how you populate the rows. For master products, each row creates a parent that variants will reference. You leave variant-specific fields empty.
ColumnRequiredTypeDescription
product_id—UUIDLeave empty to create a new master. Set to an existing UUID to update.
product_name*TextMaster product display name shown in the catalog and on quotes.
product_api_name—TextStable API identifier. Strongly recommended — variants will reference the master via this name.
reference—TextInternal reference shown to sales reps.
product_description—TextLong-form description shown on quotes and in the Dealroom.
primary_image_id—UUIDUUID of an image already uploaded to the Qwoty media library.
settings[recurrence_type]*Enumone_off for one-time purchase, recurring for subscriptions. All variants of this master inherit this value.
settings[is_active]—Booleantrue (default) to make the master visible in catalogs, false to archive.
settings[product_type]—Enumphysical, service, or subscription. Drives quote behaviour and reporting.
settings[unit_of_measure]—TextDisplay unit (for example, unit, kg, hour).
settings[language_code]—TextTwo-letter language code for localized content (en, fr, de).
settings[unit_per_pack]—NumberIf the master is sold in packs, the number of units per pack.
catalog_api_names—TextComma-separated catalog API names. Empty value attaches the workspace default catalog.
category_api_names—TextComma-separated category API names.
inventory[sku]—TextMaster-level SKU (variants override with their own).
identifiers[erp]—TextExternal ERP identifier.
identifiers[crm]—TextExternal CRM identifier.
identifiers[accounting]—TextExternal accounting identifier.
accounting[ledger_account]—TextLedger account code used for accounting reports.
shipping[weight]—NumberNet weight.
shipping[weight_unit]—Enumkg, g, lb, oz.
shipping[height]—NumberHeight in shipping[length_unit].
shipping[length]—NumberLength in shipping[length_unit].
shipping[width]—NumberWidth in shipping[length_unit].
shipping[length_unit]—Enumcm, mm, m, in.
shipping[country_of_origin]—TextISO 2-letter country code (FR, DE, CN). Used for customs and trade documents.
shipping[harmonized_system_code]—TextHarmonized System (HS) code for international shipping and customs.
When importing a master, you typically leave variant-specific fields like inventory[sku] empty if each variant has its own SKU. Use the master row to set defaults that apply across all variants (recurrence type, product type, shipping dimensions for non-varying physical products).

​
Common scenarios

​
Create master products without variants

For products that don’t have variants — a single SKU master that will later have one or more variants attached: 
product_id,product_name,product_api_name,settings[recurrence_type],settings[product_type],catalog_api_names
,Premium T-Shirt,premium_tshirt,one_off,physical,france
,Annual SaaS Plan,annual_saas_plan,recurring,subscription,saas_catalog
,Consulting Day,consulting_day,one_off,service,services
After this import, you can add variants to each master via the Products import, referencing them by product_api_name.

​
Create master products with full shipping data

For physical goods that need detailed shipping info: 
product_id,product_name,product_api_name,settings[recurrence_type],settings[product_type],shipping[weight],shipping[weight_unit],shipping[height],shipping[length],shipping[width],shipping[length_unit],shipping[country_of_origin],shipping[harmonized_system_code]
,Premium T-Shirt,premium_tshirt,one_off,physical,0.2,kg,2,30,25,cm,FR,610910
,Coffee Mug,coffee_mug,one_off,physical,0.4,kg,12,9,9,cm,DE,691200

​
Update existing master products

When product_id is set, the row updates rather than creates: 
product_id,product_description,settings[is_active]
6ddb0e85-1d1e-4c11-b45d-c9c7ff7c62e8,Premium 100% organic cotton t-shirt with reinforced seams.,true
9b7ccfa9-1234-5678-aabb-c0ffee123456,Discontinued — replaced by SKU-MUG-V2.,false
Only the columns you include are updated. Other fields stay untouched.

​
Troubleshooting

They shared the same product_name and neither had a product_api_name. Re-import with a unique product_api_name per master.
Use exactly one_off or recurring (lowercase, with underscore). Common mistakes: monthly, yearly, subscription, one-off (with dash).
Qwoty matches catalog API names exactly (case-sensitive). Check the API name in Catalog & Products → Catalogs and re-import. For multiple catalogs in one cell, use commas with no spaces and wrap the cell in double quotes: "france,partner_pricing".
The image must exist in the Qwoty media library before the import. Upload your images first, then export the media list to retrieve their UUIDs.
Boolean values must be lowercase: true or false. Uppercase TRUE or FALSE is rejected.

​
Next steps

Import products

Now that masters exist, import the variants that reference them.

Import prices

Once products exist, attach prices to them.

Prepare your CSV

Universal formatting rules.

Variants and options

Conceptual reference on the master/variant structure.