CSV format & columns¶

This is the column reference for every data type. The fastest way to a correct file is to download the template (header only) or example (header + sample rows) for your type — those headers always round-trip back through the importer. This page documents what each header means.

General rules¶

Delimiter: standard comma-separated CSV with a header row. Quote cells that contain commas or newlines.
Multi-value columns (categories, visibility, properties, media, …) hold several entries separated by the list delimiter — | by default (listDelimiter).
Category paths separate their segments with the path delimiter — > by default (categoryPathDelimiter).
Booleans are 1 / 0.
Unknown columns are ignored, and columns the live Shopware schema doesn't have are dropped — so a CSV is forward/backward compatible across Shopware versions.
Empty/missing optional cell falls back to a sensible default (e.g. an absent type becomes physical; an unknown visibility level becomes Visible everywhere).

`product`¶

A product is one row. Columns fall into five families.

Scalar columns¶

Mapped 1:1 onto product.* after value coercion:

Column	Notes
`product_number`	Key. Matches an existing product or creates a new one.
`type`	`physical` (default) or `digital`.
`price`	Gross price.
`price_net`	Net price (optional; derived from `price` + tax if omitted).
`tax_rate`	Numeric rate, e.g. `19`. Preferred — resolves unambiguously on re-import.
`tax`	Legacy alias for the tax rate (still accepted on import).
`stock`	Integer stock.
`manufacturer`	Manufacturer name (resolved to an ID; not auto-created — see note).
`manufacturer_number`	Free-text MPN.
`ean`	Free-text EAN/GTIN.
`delivery_time`	Delivery-time name (resolved to an ID).
`unit`	Unit key (resolved to an ID).
`weight`, `width`, `height`, `length`	Decimals.
`active`, `mark_as_topseller`, `is_closeout`, `shipping_free`	Booleans `1`/`0`.
`min_purchase`, `max_purchase`, `purchase_steps`, `restock_time`	Integers.
`purchase_unit`, `reference_unit`	Decimals.
`release_date`	Date/time.

Translation columns¶

name, description, meta_title, meta_description, keywords, pack_unit, pack_unit_plural. Unsuffixed = default language. Add a locale suffix for other languages:

name,name.de-DE,description,description.de-DE

On export, control which extra locales are emitted with the --locales option / profile option (e.g. de-DE,en-GB).

Association columns (multi-value)¶

Column	Format	Notes
`categories`	paths joined by `\\|`, segments by `>`	`Electronics > Phones \\| Clearance`. Missing categories auto-created if `autoCreateCategories`.
`visibility`	`Channel:level` joined by `\\|`	See visibility levels.
`properties`	`Group:Option` joined by `\\|`	`Color:Red\\|Size:M`. Missing groups/options auto-created if `autoCreatePropertyOptions`.
`media`	sources joined by `\\|`	URLs (or paths). Downloaded per the media strategy.
`advanced_prices`	tiered prices	Round-trips with export; use the example file as the format reference.
`advanced_prices_json`	raw JSON	Alternative explicit form of the above.
`cover`	single source	Export-only — the gallery cover image.

Custom field columns¶

Three accepted forms (mix freely):

custom.<name> — canonical per-field column, e.g. custom.warranty_months.
custom_<name> — legacy per-field column (still accepted).
custom_fields — a single JSON catch-all column holding all custom-field values.

Missing custom fields are auto-created under the fujin_import set when autoCreateCustomFields is on.

Per-property-group columns¶

property.<Group> puts one property group in its own column, with the option name(s) in the cell (list-delimited) — e.g. property.Color = Red. This is an alternative to packing everything into the properties column.

Visibility levels¶

A visibility entry is <SalesChannel>:<level>. The level accepts the number, the admin label, a slug, or the Shopware constant name (all case-insensitive); blank/unknown → Visible everywhere:

Level	Accepted spellings
30 Visible everywhere	`30`, `visible`, `all`, `visible everywhere`
20 Hidden in listings	`20`, `hidden_in_listings`, `search`, `hidden in listings`
10 Hidden in listings and search	`10`, `link_only`, `link`, `hidden in listings and search`

Export emits the human label (e.g. Storefront:Visible everywhere).

Canonical export column set¶

A product export emits this column order, which is exactly the inverse of what import reads — so an export file re-imports cleanly:

product_number, type,
name, description, meta_title, meta_description, keywords, pack_unit, pack_unit_plural,
price, price_net, tax_rate, stock,
manufacturer, manufacturer_number, ean, delivery_time, unit,
weight, width, height, length,
active, mark_as_topseller, is_closeout, shipping_free,
min_purchase, max_purchase, purchase_steps, purchase_unit, reference_unit, restock_time, release_date,
categories, visibility, properties, advanced_prices, media, cover,
custom_fields

Install-aware exports also append a property.<Group> column per property group and a custom.<Field> column per custom field.

Worked example¶

product_number,type,name,price,tax_rate,stock,manufacturer,active,categories,visibility,properties,media
SKU-1,physical,Example Phone,19.99,19,100,Example Manufacturer,1,Example Catalog > Electronics > Phones,Storefront:Visible everywhere,Color:White|Material:Glass,https://example.com/images/sku-1.jpg
SKU-2,digital,Example Voucher,9.99,7,0,,1,Example Catalog > Software,Storefront:Hidden in listings,Color:Black,

`product_variants`¶

product_number, parent_product_number, type, variant_options,
name, price, price_net, stock,
ean, manufacturer_number, weight, width, height, length, active,
media, custom_fields

product_number — the variant's own SKU.
parent_product_number — the parent product (resolved; optionally auto-created via autoCreateVariantParents).
variant_options — Group:Option joined by |, e.g. Size:M.

`category`¶

category_path, active, visible, type, image,
description, meta_title, meta_description, keywords

category_path — full path, segments joined by >. Created under the configured parent (default storefront root) if absent.
name — optional column; overrides the leaf segment as the category name.
type — page (default) or link.
image — URL, downloaded and linked as the category's media.
active, visible — booleans.
description, meta_*, keywords — translatable fields.

`inventory`¶

product_number, stock

Updates stock (and the denormalised available stock) on existing products only — does not create products. The fast path for recurring stock syncs.

`entities_metadata`¶

Multi-row-type. A _row_type column tags each row:

_row_type, group_name, sorting_type, display_type,
option_name, option_position,
custom_field_set_name, custom_field_name, custom_field_type

`_row_type`	Required cells	Creates
`PROPERTY_GROUP`	`group_name`, `sorting_type`, `display_type`	a property group
`PROPERTY_GROUP_OPTION`	`group_name`, `option_name`, `option_position`	an option under that group
`CUSTOM_FIELD_SET`	`custom_field_set_name`	a custom field set
`CUSTOM_FIELD`	`custom_field_set_name`, `custom_field_name`, `custom_field_type`	a custom field in that set

Order rows so a group/set appears before the options/fields that depend on it. Example:

_row_type,group_name,sorting_type,display_type,option_name,option_position,custom_field_set_name,custom_field_name,custom_field_type
PROPERTY_GROUP,Color,alphanumeric,text,,,,,
PROPERTY_GROUP_OPTION,Color,,,White,1,,,
PROPERTY_GROUP_OPTION,Color,,,Black,2,,,
CUSTOM_FIELD_SET,,,,,,example_set,,
CUSTOM_FIELD,,,,,,example_set,warranty_months,int

`product_extra`¶

Multi-row-type. Attaches extra data to existing products:

_row_type, product_number, group_name, option_name, custom_field_name, custom_field_value

`_row_type`	Required cells	Effect
`PRODUCT_PROPERTY`	`product_number`, `group_name`, `option_name`	links the product to that property option
`PRODUCT_CUSTOM_FIELD`	`product_number`, `custom_field_name`, `custom_field_value`	sets one custom-field value (merged into the product's `custom_fields` JSON)

_row_type,product_number,group_name,option_name,custom_field_name,custom_field_value
PRODUCT_PROPERTY,SKU-1,Color,White,,
PRODUCT_PROPERTY,SKU-1,Material,Glass,,
PRODUCT_CUSTOM_FIELD,SKU-1,,,warranty_months,24

`rules`¶

name, priority, description, conditions, areas, module_types

name — key; re-importing the same name updates the rule.
priority — integer.
conditions — JSON. A flat array of leaves is auto-wrapped into an AND container; a full nested tree object is used as-is. [] means "always matches".
areas, module_types — JSON passthrough (round-trips on export).

name,priority,description,conditions,areas,module_types
Example — Cart total >= 100,10,Cart total is at least 100.,"[{""type"":""cartCartAmount"",""value"":{""operator"":"">="",""amount"":100}}]",,

How references resolve¶

Codes/names/paths in the CSV are turned into Shopware IDs in Pass A by dedicated resolvers, several of which auto-create the target when allowed:

CSV value	Resolver	Auto-create?
`categories` paths	category path resolver	yes — `autoCreateCategories`
`properties` / `variant_options`	property group + option resolvers	yes — `autoCreatePropertyOptions`
`custom.*` / `custom_fields` keys	custom-field resolver	yes — `autoCreateCustomFields`
`parent_product_number`	product-number resolver	optional stub — `autoCreateVariantParents`
`manufacturer`	manufacturer resolver	no (missing → skipped with a warning)
`delivery_time`, `unit`, `tax_rate`/`tax`	delivery-time / unit / tax resolvers	no
`visibility` channel	sales-channel resolver	no
`rules` name	rule resolver	n/a (rules are the entity)