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