Importable product columns reference

This page is the complete lookup for every column the Products page spreadsheet importer reads, plus the exact validation each one is subject to. It's the reference companion to the task guide Import products from a spreadsheet — read that first if you want the step-by-step flow; come here to look up a specific column, its accepted values, or an edge case.

Everything below is read straight from the importer, so it's authoritative for what the Import Products modal accepts. The Product fields & validation reference covers the same fields as they behave on the product record itself.

Before you begin

• Importing requires the Import permission under Products in your role. See Product permissions reference.
• Every lookup column resolves a value to an existing record in your account by name (case-insensitive). The importer never creates brands, categories, suppliers, tax rates, or nominal codes for you — an unknown name is a row error. Set them up first: Manage brands, Manage categories, Set a product's accounting.

File formats and how columns are read

Aspect	Behavior
Accepted file types	.csv, .tsv, .txt, .xlsx, .xls, or pasted delimited text.
Delimiter	Auto-detected (comma, tab, or semicolon).
Header row	Auto-detected; you confirm the First row is a header checkbox before mapping.
Column mapping	Each file column is mapped to a target field via a Maps To dropdown. Common header names auto-match (for example UPC, EAN, GTIN → barcode); anything else you map by hand or set to Skip this column.
Case sensitivity	SKU matching, duplicate detection, and all name lookups (brand, category, supplier, tax rate, nominal codes) are case-insensitive. Fixed keyword values are not — type and the unit codes must be lowercase (standard, not Standard; kg, not KG), or the row errors.
Blank cells	For most fields a blank cell means "leave unchanged" on an update (see the numeric and boolean rules below).

Column headers don't have to match exactly — mapping is what binds a file column to a target field. The account template guarantees the header names the auto-matcher recognizes. To get a spreadsheet pre-populated with your catalog, use Export products; its output re-imports cleanly.

Identity and match columns

Column	Required	Type / format	Accepted values	Notes
id	No	Integer	An existing product ID	When mapped and non-blank, forces an update-by-ID match. A non-numeric or unknown ID is a row error.
sku	Yes	Text	Any	The match key. Case-insensitive; must be unique within the file (a repeat is an error on every occurrence).
name	Yes	Text	Any	Product name.
type	No	Text	standard, bundle, kit	Defaults to standard on create. Only standard, bundle, and kit are importable here — matrix, blemished, and manufactured aren't. Omitting the column on an update preserves the existing type. See Convert & auto-detect product types.
product_type	No	Text	A product type path or a unique leaf name	A different field from type above. Matched against your own product type tree — full path first (Baby clothing > Accessories > Hats & beanies), then a bare leaf name if it's unique. Never creates a missing type; an unmatched or ambiguous value is an error on that row. Blank leaves the existing type untouched. See Import & export product types.
barcode	No	Text	UPC / EAN / ISBN / GTIN	Scientific-notation values are rejected — see the caveat below.
mpn	No	Text	Any	Manufacturer part number.

Name-lookup columns

Each of these resolves a value to a record that must already exist in your account. The match is by name, case-insensitive; an unknown value is a row error naming the field.

Column	Resolves to	Notes
brand	A brand	See Manage brands.
category	A category	Set as the product's primary category. See Manage categories.
default_tax_rate	A tax rate
default_supplier_name	A supplier	Creates or updates the product's default supplier link. See Manage a product's suppliers.

Account columns

The six account columns set a product's own account override — the account that wins over every account rule for that product. Most catalogs don't need them: let rules send whole categories or brands to their accounts, and use these columns only for exceptions.

Column	The account for
sales_nominal_code	Sales
cogs_nominal_code	Cost of goods sold
inventory_nominal_code	Stock on hand
inventory_in_transit_nominal_code	Stock in transit
accrued_purchases_nominal_code	Goods received but not yet billed
discount_nominal_code	Discounts

Each column accepts:

Value	Effect
blank	Leaves the product's override as it is.
An account number, such as 4010	Sets the override to that account.
The number and name, such as 4010 Apparel Sales, 4010 - Apparel Sales or 4010: Apparel Sales	Sets the override to that account.
The account name on its own, such as Apparel Sales (case-insensitive)	Sets the override to that account. A name shared by two accounts is a row error; use the number.
ACCOUNT_RULE (case-insensitive)	Clears the override, so the product follows the account rules again.

An unknown account, or an archived one, is a row error that names it.

Account number columns. Each account column also has a …_number partner — sales_nominal_code_number, cogs_nominal_code_number and so on — which the product export writes next to the account name. When a …_number cell is filled, it wins over the name column and must be an exact account number. That's what lets an exported sheet import back cleanly, even when two of your accounts share a name. ACCOUNT_RULE works in the number column too.

Dimensions, weights, and case packing

All are optional numbers that must be non-negative. Blank leaves the field unchanged on an update.

Column	Type / format	Accepted values
weight	Number ≥ 0
weight_unit	Text	kg, g, lb, oz
length / width / height	Number ≥ 0
dimension_unit	Text	cm, mm, in, ft, m
case_quantity	Number ≥ 0	Units per case
case_weight	Number ≥ 0
case_weight_unit	Text	kg, g, lb, oz
case_length / case_width / case_height	Number ≥ 0
case_dimension_unit	Text	cm, mm, in, ft, m

Weight and dimension units default to your account settings only when the product is created and the unit column is blank. On an update, units change only when you explicitly provide the unit column.

Proforma / landed-cost columns

Column	Type / format	Notes
unit_cost	Number ≥ 0	Fallback cost used for valuation when no PO or FIFO history exists. See FIFO layers & COGS.
proforma_shipping_cost	Number ≥ 0	Estimated landed shipping per unit.
proforma_landed_cost_percentage	Number ≥ 0	Percentage.
proforma_marketplace_cost_percentage	Number ≥ 0	Percentage.

Stock, demand-planning, and boolean columns

Column	Type / format	Accepted values	Notes
min_stock_level	Integer ≥ 0		Reorder-alert threshold.
daily_average_consumption	Number ≥ 0		Demand-planning input.
daily_average_consumption_net_returns	Number ≥ 0		Demand-planning input.
is_dropshippable	Boolean	yes, true, 1, y → true	Blank leaves it unchanged; any other non-blank value is false.
is_taxable	Boolean	yes, true, 1, y → true	Blank leaves it unchanged; any other non-blank value is false.
fba_prep_instructions	Text	Any	Free text.
tags	Text	Comma-separated	Synced to the product's tags.

The importer only sets stock-related fields on the product record; it doesn't create opening inventory. To seed starting stock, see Set up product inventory.

Default-supplier link columns

These write to the product's default supplier link (the one named by default_supplier_name). Mapping behavior is deliberate: a column that's mapped but left blank clears the field, while an unmapped column preserves the existing value — so a partial-update sheet touches only the fields you include.

Column	Type / format	Notes
default_supplier_sku	Text	Mapped-blank clears; unmapped preserves.
default_supplier_leadtime	Integer ≥ 0	Mapped-blank clears; unmapped preserves.
default_supplier_moq	Number ≥ 0	Mapped-blank clears; unmapped preserves.
default_supplier_target_stock_days	Integer ≥ 0	Mapped-blank clears; unmapped preserves.

Image columns (image_url_1 … image_url_9)

You can supply up to nine image URLs per row: image_url_1 is the primary image and image_url_2 through image_url_9 are additional gallery images. URLs are downloaded through the standard product-image pipeline. See Add & manage product images.

Rule	Behavior
Required scheme	Must start with http:// or https://, and be a valid URL — otherwise it's a per-image error.
Length	Each URL must be at most 2048 characters; over-length is a per-image error.
Primary	image_url_1 is primary. If it's blank or invalid but other slots have images, the first surviving image is promoted to primary.
Duplicates	A URL that repeats within the row (case-insensitive) is skipped with a warning.
No image columns mapped	Existing product images are left unchanged.
Columns mapped but all blank	Existing images are left unchanged, and the row gets a warning.
Any image cell populated	The row's images replace the product's existing image set.

Dynamic attribute columns (attribute_<id>)

For every attribute in your account, the mapping list offers a column labelled Attr: <name> that maps to attribute_<id>. A non-blank value upserts that attribute value on the product; a blank value is ignored. See Manage attributes and the Attribute fields & types reference.

Component columns

Kit and bundle composition can be imported with these columns. Component links are wired up after every product in the batch has been created or updated, so a component referenced by SKU or ID resolves regardless of row order. The value format is IDENTIFIER->QTY, comma-separated for multiple entries (the -> or a → arrow both work; quantity defaults to 1 and is floored at 1).

Column	Format	Effect
component_skus	SKU->QTY, SKU2->QTY2	Attaches the listed products as components of this kit/bundle, by SKU.
component_ids	ID->QTY, ...	Same, matching components by product ID.
component_of_sku	SKU->QTY, ...	Makes this product a component of the named parent products, by SKU.
component_of_id	ID->QTY, ...	Same, matching parents by ID.

Attaching components re-syncs the parent's component set to exactly what the column lists (components not listed are detached). To build kits and bundles visually instead, see Build bundles & kits in the Workshop; for the underlying model, see the Kit & bundle component reference.

Lifecycle, successor, and season columns

These columns set a product's lifecycle state, its successor, its product seasons and its never-out-of-stock flag. In the Maps To dropdown they appear as Lifecycle State, Lifecycle Reason, Discontinue On, Last Order Date, Successor SKU, Successor Pack Factor, Seasons and Never Out Of Stock. A blank cell leaves that value as it is.

Column	Accepted values	Notes
lifecycle_state	A state's name, such as Discontinued, including states you created	The change is recorded in the product's lifecycle history as a CSV import. A matrix product's variants don't follow the parent: list each variant on its own row.
lifecycle_reason	A reason, such as Brand decision or Replaced by a new product	Leave it blank when you move a product to Phasing out or Discontinued and the reason is recorded as Other, with a warning.
discontinue_on	A date after today	Required when lifecycle_state is Phasing out.
last_order_date	A date	Must be on or before discontinue_on.
successor_sku	An existing product's SKU	Links the successor with the default options. A product can't be its own successor, and an import can't remove a successor link.
successor_pack_factor	A number greater than zero	Ignored, with a warning, when successor_sku is blank.
seasons	Product season codes separated by a pipe, such as SS26|AW26	Each code must already exist under Settings → Products → Product seasons.
noos	Yes or No	Sets Never out of stock (core) by hand, so the nightly automatic check no longer changes it.

Changing any of the first six columns needs the Products → Lifecycle permission. Without it, a row that would change a lifecycle or successor value fails with an error naming the columns, while rows whose values match the product's current ones import normally. The full list of messages, and the export side, is in Import and export lifecycle data.

Validation rules at a glance

Field kind	Rule	Blank cell
Numeric (costs, weights, dimensions, consumption, MOQ)	Must be numeric and non-negative; otherwise a row error.	Treated as null → field left unchanged on update.
Integer (min_stock_level, default_supplier_leadtime, default_supplier_target_stock_days)	Must be a whole number and non-negative; a decimal or non-number is a row error.	Treated as null → unchanged.
Boolean (is_dropshippable, is_taxable)	yes / true / 1 / y (any case) → true; any other non-blank value → false.	Treated as null → unchanged.
Weight unit	One of kg, g, lb, oz (lowercase, exact match).	Defaults to account setting on create only.
Dimension unit	One of cm, mm, in, ft, m (lowercase, exact match).	Defaults to account setting on create only.
Type	One of standard, bundle, kit (lowercase, exact match).	Defaults to standard on create; preserved on update.

Barcode scientific-notation guard

Excel silently rewrites long numeric barcodes into scientific notation — for example 810000000000 becomes 8.10E+11. The Products-page importer detects any barcode that looks like scientific notation and rejects the row rather than storing a corrupted value, with a message telling you to re-export the source file and avoid opening it in Excel first. If you hit that error, upload the freshly exported file without opening it in a spreadsheet app.

Pricing columns (Price: <tier>)

For every pricing tier in your account, the mapper offers a Price: <tier> target (for example Price: Retail). Map a column to one to set that tier's selling price on the product.

Column	Type	Notes
Price: <tier>	Number ≥ 0	Sets the product's selling price for that absolute pricing tier — one column per tier. Only the tiers you map are changed; unmapped tiers keep their current price. If the product has no price for the tier yet, one is created. Blank cells are skipped; an unknown tier errors the row.

The separate unit_cost column sets the product's fallback cost, not a selling price — the two are independent. Relative tiers are derived from a base tier and aren't set directly (see Relative pricing tiers). To set prices without a file, use Bulk-edit products or a product's pricing screen.

Read-only export columns (never imported)

A file exported from SKU carries computed columns that can't be imported. The mapper recognizes them and labels them (read-only) instead of offering them as mappable fields, so you can re-import an export without stripping them out. These include: average cost and its currency, total / available / on-hold / incoming / in-transit inventory, stock value, archived_at, created_at, updated_at, and the last COGS-rebuild timestamp.

Columns available only in the generic Data Imports importer

The Products page always uses the importer documented here. A separate generic Data Imports framework has its own product definition that accepts a few extra columns not reachable from the Products page Import button:

Column	What it does (generic path only)
stock_uom_code	Sets the product's stock unit of measure by code. See Units of measure reference.
default_supplier_tier_<id>	Sets a per-supplier pricing-tier price on the default supplier link. (Product selling-price tiers are importable on the Products page — see Pricing columns above.)

If you map these on the Products page importer they have no effect — use the generic Data Imports path (or the relevant settings pages) when you need them. Relative-tier behavior is explained in Relative pricing tiers.

Next steps

• Import products from a spreadsheet — the full task flow, including update-vs-create and background-job handling.
• Export products — produce a re-importable spreadsheet of your catalog.
• Product fields & validation reference — how these fields behave on the product record.
• Product permissions reference — who can import.