Prepare your import file
Most failed imports fail here, not in the upload. An hour on the file saves a day of fixing rows.
The import reads a CSV file keyed on the sku column. A row whose SKU already
exists updates that product; a row with a new SKU creates one. Everything else
in this article follows from that one rule: the file has to carry the codes the
catalog uses, in the columns the import expects, with the SKUs your ERP knows.
Start from an export
Create one product by hand (Create a product), then select Export on PIM › Products. You now have a CSV with exactly the right columns, in exactly the right order, with one correct row as a worked example.
Build your import on top of that. Do not construct the header row from memory.
Column rules
One column per attribute, named by the attribute code: thread_size, never
the label "Thread size" or "Gewindegröße". Then, depending on the attribute:
| Attribute | Columns | Value |
|---|---|---|
| Plain | weight | The value |
| Localizable | One per language: description-de_DE, description-en_GB | The text in that language |
| Scopable | One per channel: name-web, name-punchout | The value for that channel |
| Localizable and scopable | One per combination: name-web-de_DE | |
| Select | material | The option code: v4a, never "Stainless steel V4A" |
| Measurement | Usually two: weight and weight-unit, or one combined column | Value and unit; check what the export produced |
| Reference | manufacturer | The record code |
| Multi-select, multi-value | One column | Values with a separator, usually a comma; check your export |
Select values as labels instead of option codes are the most common single cause of rejected rows.
The identifiers
| Column | Meaning |
|---|---|
sku | The product identifier. Existing SKU = update, new SKU = create. |
family | The family code. Required when creating. |
parent | For variants: the SKU of the product model. |
categories | Category codes, comma-separated. |
enabled | 1 / 0. |
Encoding and format
- UTF-8. Excel's default CSV export on Windows is often not UTF-8, and that
is what turns
GrößeintoGröße. Save explicitly as CSV UTF-8. - Decimal separator. Check whether your file uses
.or,and whether that matches what the import expects.10,5read as a thousands separator becomes105. - Leading zeros. Excel eats them. A SKU of
0041711becomes41711. Format the column as text before you type anything, or your import will not match. - Line breaks inside fields must be quoted properly. Long descriptions with paragraphs are where this bites.
Test with 10 rows
Always. Take ten representative rows, including your most awkward product and one variant, and import those first.
Check the result in the Cockpit:
- Did the values land in the right fields?
- Did select values resolve to options, or arrive as blanks?
- Are umlauts intact?
- Are numbers correct, with the right unit?
- Did completeness go where you expected?
Only then run the full file.
A pre-flight checklist
- File is UTF-8
- Header row uses attribute codes
- Localizable and scopable columns are suffixed correctly
- Select values are option codes
- Reference values are record codes
- SKUs match your ERP, leading zeros intact
- Decimal separator is right
- Ten-row test import checked field by field