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

# Import master products

> Create master products that group multiple variants together. Always import these first.

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.

<Note>
  You must have the **Admin** role with **Data → Import CSV** authorized. See [Manage roles](/user-guide/settings/users/manage-roles) for permission details.
</Note>

## Open the import

<Steps>
  <Step title="Open Settings">
    In the left sidebar, click **Settings**.
  </Step>

  <Step title="Navigate to Import/Export Data">
    Under the **Data** section, click **Import/Export**.
  </Step>

  <Step title="Select Master products">
    Tick the **Master products** card at the top of the page. The Import and Export sections below adapt.
  </Step>

  <Step title="Click Download example file">
    Get the sample CSV with the right column headers.
  </Step>

  <Step title="Click Import">
    Drop your prepared file. The 4-step wizard runs: **Upload → Mapping → Confirm → Result**.
  </Step>
</Steps>

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

<Info>
  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).
</Info>

## 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:

```csv theme={null}
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](/user-guide/data-migration/how-tos/import-products), referencing them by `product_api_name`.

### Create master products with full shipping data

For physical goods that need detailed shipping info:

```csv theme={null}
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:

```csv theme={null}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="settings[recurrence_type] was rejected">
    Use exactly `one_off` or `recurring` (lowercase, with underscore). Common mistakes: `monthly`, `yearly`, `subscription`, `one-off` (with dash).
  </Accordion>

  <Accordion title="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"`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="settings[is_active] = TRUE returned an error">
    Boolean values must be lowercase: `true` or `false`. Uppercase `TRUE` or `FALSE` is rejected.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Import products" icon="box" href="/user-guide/data-migration/how-tos/import-products">
    Now that masters exist, import the variants that reference them.
  </Card>

  <Card title="Import prices" icon="tag" href="/user-guide/data-migration/how-tos/import-prices">
    Once products exist, attach prices to them.
  </Card>

  <Card title="Prepare your CSV" icon="file-spreadsheet" href="/user-guide/data-migration/how-tos/prepare-csv-files">
    Universal formatting rules.
  </Card>

  <Card title="Variants and options" icon="sitemap" href="/user-guide/catalog/reference/variants-and-options">
    Conceptual reference on the master/variant structure.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.