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

> Import products and product variants linked to existing master products and catalogs.

The Products import creates the actual sellable items: simple products with no variants, or variants attached to a master product. Import master products **first** if your products reference them.

<Note>
  You must have the **Admin** role with **Data → Import CSV** authorized.
</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 Products">
    Tick the **Products** card at the top of the page.
  </Step>

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

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

## CSV columns reference

The Products template uses the same columns as Master products. The difference is what you populate — for products and variants, the rows reference an existing master through `parent_product_api_name` or are standalone single-variant items.

| Column                             | Required | Type    | Description                                                                                |
| ---------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
| `product_id`                       | —        | UUID    | Leave empty to **create** a new product. Set to an existing UUID to **update**.            |
| `product_name`                     | \*       | Text    | Product or variant display name (for example, `Premium T-Shirt - Blue / M`).               |
| `product_api_name`                 | —        | Text    | Stable API identifier for this specific product or variant.                                |
| `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` or `recurring`. Must match the master's recurrence type if attached to a master. |
| `settings[is_active]`              | —        | Boolean | `true` (default) or `false`.                                                               |
| `settings[product_type]`           | —        | Enum    | `physical`, `service`, or `subscription`.                                                  |
| `settings[unit_of_measure]`        | —        | Text    | Display unit (for example, `unit`, `kg`, `hour`).                                          |
| `settings[language_code]`          | —        | Text    | Two-letter language code (`en`, `fr`, `de`).                                               |
| `settings[unit_per_pack]`          | —        | Number  | Number of units per pack, when sold in packs.                                              |
| `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    | SKU for this product or variant.                                                           |
| `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 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`).                                              |
| `shipping[harmonized_system_code]` | —        | Text    | Harmonized System (HS) code for international shipping.                                    |

<Warning>
  When `catalog_api_names` or `category_api_names` contain multiple values, the cell must be wrapped in double quotes and use **commas** as the internal separator: `"france,partner_pricing"`. Without the quotes, the comma inside the cell breaks the CSV row.
</Warning>

<Info>
  Variants attached to a master inherit the master's `settings[recurrence_type]`, `settings[product_type]`, and shipping defaults. You can still set them on the variant row to override — but they must be consistent or Qwoty rejects the row.
</Info>

## Common scenarios

### Create simple, single-variant products

For a list of one-off products with no variants:

```csv theme={null}
product_id,product_name,product_api_name,settings[recurrence_type],settings[product_type],catalog_api_names,inventory[sku]
,Wireless Mouse,wireless_mouse,one_off,physical,france,SKU-001
,USB-C Cable,usb_c_cable,one_off,physical,france,SKU-002
,Laptop Stand,laptop_stand,one_off,physical,france,SKU-003
```

### Create variants attached to existing master products

You've already imported a `Premium T-Shirt` master with `product_api_name = premium_tshirt`. Now add three variants:

```csv theme={null}
product_id,product_name,settings[recurrence_type],inventory[sku],identifiers[erp]
,Premium T-Shirt - Blue / S,one_off,SKU-PT-BS,ERP-PT-BS
,Premium T-Shirt - Blue / M,one_off,SKU-PT-BM,ERP-PT-BM
,Premium T-Shirt - Blue / L,one_off,SKU-PT-BL,ERP-PT-BL
```

<Info>
  The way variants attach to master products depends on your workspace configuration (typically through `parent_product_api_name` or `product_parent_id`). Check the example file downloaded from the import screen — it includes the relation columns specific to your workspace.
</Info>

### Update existing products

Export your current products to retrieve their UUIDs, then re-import with the changes:

```csv theme={null}
product_id,product_name,inventory[sku]
6ddb0e85-1d1e-4c11-b45d-c9c7ff7c62e8,Wireless Mouse Pro,SKU-001-PRO
9b7ccfa9-1234-5678-aabb-c0ffee123456,USB-C Cable v2,SKU-002-V2
```

Only the columns you include get updated. Other fields stay untouched.

### Bulk update SKUs across catalogs

Useful when migrating from another system:

```csv theme={null}
product_id,inventory[sku],identifiers[erp]
6ddb0e85-1d1e-4c11-b45d-c9c7ff7c62e8,NEW-SKU-001,ERP-NEW-001
9b7ccfa9-1234-5678-aabb-c0ffee123456,NEW-SKU-002,ERP-NEW-002
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="My import failed because of an invalid recurrence_type">
    The only accepted values for `settings[recurrence_type]` are `one_off` and `recurring` (lowercase, with underscore). Common mistakes: `monthly`, `yearly`, `subscription`, `one-off` (with dash).
  </Accordion>

  <Accordion title="The catalog_api_names column references a catalog that wasn't found">
    Qwoty matches catalog API names exactly (case-sensitive). Check the catalog API names in **Catalog & Products → Catalogs**. For multiple catalogs, use commas inside the cell with no spaces, and wrap the value in double quotes: `"france,partner_pricing"`.
  </Accordion>

  <Accordion title="primary_image_id rows fail with 'Unknown reference'">
    The UUID in `primary_image_id` doesn't match any image in your media library. Upload your images first, export the media list to get their UUIDs, then update your CSV.
  </Accordion>

  <Accordion title="A product was created but doesn't appear in the catalog">
    Check that `catalog_api_names` is populated. If empty, the product is attached only to the workspace's default catalog (which may be hidden from your sales reps).
  </Accordion>

  <Accordion title="My update by product_id replaced fields I didn't include">
    Updates only modify the columns present in the CSV. If a field looks empty after import, check that you didn't leave the column header in the file with all-empty values — that overwrites the field.
  </Accordion>

  <Accordion title="My boolean field returned an error">
    Use lowercase `true` or `false`. Uppercase `TRUE` or `FALSE`, or `1` / `0`, are rejected.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Import prices" icon="tag" href="/user-guide/data-migration/how-tos/import-prices">
    Now that products exist, attach prices to them.
  </Card>

  <Card title="Import master products" icon="layer-group" href="/user-guide/data-migration/how-tos/import-master-products">
    If you skipped this step, import master products first.
  </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="Catalogs" icon="box" href="/user-guide/catalog/introduction">
    Manage where products live.
  </Card>
</CardGroup>