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


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