wiggleverse-ecomm/backend/app/domains/products/columns.md

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