Import master products

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

Open Settings

In the left sidebar, click Settings.

Navigate to Import/Export Data

Under the Data section, click Import/Export.

Select Master products

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

Click Download example file

Get the sample CSV with the right column headers.

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.

Column	Required	Type	Description
`product_id`	—	UUID	Leave empty to create a new master. Set to an existing UUID to update.
`product_name`	*	Text	Master product display name shown in the catalog and on quotes.
`product_api_name`	—	Text	Stable API identifier. Strongly recommended — variants will reference the master via this name.
`reference`	—	Text	Internal reference shown to sales reps.
`product_description`	—	Text	Long-form description shown on quotes and in the Dealroom.
`primary_image_id`	—	UUID	UUID of an image already uploaded to the Qwoty media library.
`settings[recurrence_type]`	*	Enum	`one_off` for one-time purchase, `recurring` for subscriptions. All variants of this master inherit this value.
`settings[is_active]`	—	Boolean	`true` (default) to make the master visible in catalogs, `false` to archive.
`settings[product_type]`	—	Enum	`physical`, `service`, or `subscription`. Drives quote behaviour and reporting.
`settings[unit_of_measure]`	—	Text	Display unit (for example, `unit`, `kg`, `hour`).
`settings[language_code]`	—	Text	Two-letter language code for localized content (`en`, `fr`, `de`).
`settings[unit_per_pack]`	—	Number	If the master is sold in packs, the number of units per pack.
`catalog_api_names`	—	Text	Comma-separated catalog API names. Empty value attaches the workspace default catalog.
`category_api_names`	—	Text	Comma-separated category API names.
`inventory[sku]`	—	Text	Master-level SKU (variants override with their own).
`identifiers[erp]`	—	Text	External ERP identifier.
`identifiers[crm]`	—	Text	External CRM identifier.
`identifiers[accounting]`	—	Text	External accounting identifier.
`accounting[ledger_account]`	—	Text	Ledger account code used for accounting reports.
`shipping[weight]`	—	Number	Net weight.
`shipping[weight_unit]`	—	Enum	`kg`, `g`, `lb`, `oz`.
`shipping[height]`	—	Number	Height in `shipping[length_unit]`.
`shipping[length]`	—	Number	Length in `shipping[length_unit]`.
`shipping[width]`	—	Number	Width in `shipping[length_unit]`.
`shipping[length_unit]`	—	Enum	`cm`, `mm`, `m`, `in`.
`shipping[country_of_origin]`	—	Text	ISO 2-letter country code (`FR`, `DE`, `CN`). Used for customs and trade documents.
`shipping[harmonized_system_code]`	—	Text	Harmonized 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

Two unrelated products got merged into the same master

They shared the same product_name and neither had a product_api_name. Re-import with a unique product_api_name per master.

settings[recurrence_type] was rejected

Use exactly one_off or recurring (lowercase, with underscore). Common mistakes: monthly, yearly, subscription, one-off (with dash).

My catalog_api_names value isn't recognized

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

primary_image_id is rejected as 'Unknown reference'

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.

settings[is_active] = TRUE returned an error

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.

Quotes

Catalog & Products

Customers

Templates

Dealroom

Documents & Models

Settings (Admin)

Data migration

Data Model

Troubleshooting

Import master products

Open the import

CSV columns reference

Common scenarios

Create master products without variants

Create master products with full shipping data

Update existing master products

Troubleshooting

Next steps

Import products

Import prices

Prepare your CSV

Variants and options

​Open the import

​CSV columns reference

​Common scenarios

​Create master products without variants

​Create master products with full shipping data

​Update existing master products

​Troubleshooting

​Next steps

Import products

Import prices

Prepare your CSV

Variants and options

Open the import

CSV columns reference

Common scenarios

Create master products without variants

Create master products with full shipping data

Update existing master products

Troubleshooting

Next steps