# Product CSV — column reference

This is the complete reference for the product CSV you import into and export from
your store (SD-0002 §6.5.1). The format is **canonical** — a clean superset of the
Shopify product CSV — and a **Shopify product CSV** imports directly too: we detect
which one you uploaded and map it for you (see *Shopify dialect* below).

You don't pick a format. Upload your file; the preview tells you which format was
recognized and shows exactly what will change before anything is applied.

## File shape

- UTF-8 (a byte-order mark is tolerated), comma-delimited, RFC 4180 quoting.
- A header row is **required**. `Handle` and `Title` are the only always-required
  columns.
- Up to 5,000 rows and 10 MB per file. Split larger catalogs and import in parts.

## Row grammar

Consecutive rows that share a `Handle` describe **one product**. The product's first
row carries the product-level fields (`Title` is required there). Each row may carry:

- a **variant** — its `Option n Value`s plus `Variant *` fields;
- an **image** — `Image Src` with `Image Position` / `Image Alt Text`;
- or both.

An image-only row (just `Handle` + `Image *`) is valid — that's how a product carries
more images than it has variants.

## Updating: blank vs. absent

- A column **absent from your file** is left untouched on existing products.
- A cell that is **present but empty** clears that field (resets it to its default).

Every clear is shown explicitly in the preview, so this is deliberate, visible
behavior — never a silent surprise.

## Canonical columns

| Column | Level | Required | Notes |
| --- | --- | --- | --- |
| `Handle` | product | every row | Identity: lowercase letters, numbers, and dashes. |
| `Title` | product | first row of a product | |
| `Description` | product | — | HTML allowed; sanitized on import. |
| `Vendor` | product | — | Free text. |
| `Type` | product | — | `standalone` (default). `kit_virtual` / `kit_assembled` are reserved; any non-`standalone` value is a row error until kits ship. |
| `Google Product Category` | product | — | Taxonomy string. |
| `Tags` | product | — | Comma-separated within the cell. |
| `Status` | product | — | `draft` \| `active` \| `archived`; defaults to `active` on add. |
| `Published` | product | — | `TRUE` \| `FALSE`; defaults to `TRUE` on add. |
| `Option1 Name` … `Option3 Name` | product | with values | e.g. "Size". A value without its name is a row error. |
| `Option1 Value` … `Option3 Value` | variant | per variant | The variant's identity combination. |
| `Variant SKU` | variant | — | Indexed; not identity. |
| `Variant Barcode` | variant | — | |
| `Variant Price` | variant | — | Decimal; no currency symbol. |
| `Variant Cost` | variant | — | Decimal. |
| `Variant Weight` + `Variant Weight Unit` | variant | — | Decimal weight plus a unit string. |
| `Variant Volume` + `Variant Volume Unit` | variant | — | Decimal volume plus a unit string. |
| `Variant Tax ID 1` / `Variant Tax ID 2` | variant | — | Opaque references. |
| `Variant Inventory Tracker` | variant | — | |
| `Variant Inventory Qty` | variant | — | Integer ≥ 0. |
| `Variant Position` | variant | — | Display order; defaults to file order. |
| `Image Src` | image | — | URL (or a store-hosted URL on re-import). |
| `Image Position` | image | — | Integer order. |
| `Image Alt Text` | image | — | |
| `Variant Image` | variant | — | URL for this variant's specific image. |
| `Component 1 SKU` / `Component 1 Quantity` … `Component 10 …` | variant | — | Reserved for kits — a non-empty value is a row error today. |

## Shopify dialect

If you upload a **Shopify product CSV**, we recognize it by its header set and map it
to the canonical columns automatically. The preview labels it *"Shopify product
CSV — mapped"*.

**Mapped — renamed**

| Shopify column | Becomes |
| --- | --- |
| `Body (HTML)` | `Description` |
| `Product Category` | `Google Product Category` |
| `Cost per item` | `Variant Cost` |
| `Variant Grams` | `Variant Weight` (in grams) |

**Mapped — same name:** `Handle`, `Title`, `Vendor`, `Tags`, `Published`, `Status`,
`Option1–3 Name` / `Option1–3 Value`, `Variant SKU`, `Variant Barcode`,
`Variant Price`, `Variant Inventory Tracker`, `Variant Inventory Qty`,
`Variant Image`, `Image Src`, `Image Position`, `Image Alt Text`.

**Not imported — listed in the preview as a heads-up, never silently dropped:** the
Shopify free-text `Type` (canonical `Type` is structural, so we don't fold a category
string into it), `Variant Compare At Price`, `Variant Inventory Policy`,
`Variant Fulfillment Service`, `Variant Requires Shipping`, `Variant Taxable`,
`Variant Tax Code`, `Gift Card`, SEO fields, every `Google Shopping / …` field, and
market/region price columns. These have no canonical home yet; your other data still
imports.