Product import#

Bulk creation or update of products and their variants from a single file (XML, CSV or JSON). Useful for the initial catalogue load, regular data feeds from a supplier, or a bulk price/stock update from a spreadsheet.

Find it under Eshop → Import produktů. Both the upload screen and the overview also carry a direct "Nápověda – manuál formátu" ("Help – file format manual") link that brings you straight to this page from the admin.

What the import does and does not do#

The import creates and updates products and product sets — it never deletes them. To pull goods off sale, deactivate them in the file (activated="0"); deleting is a manual step in the grid.

Code lists in the file are only matched by name — if the name does not exist in the system, the import will, in most cases, simply skip that value instead of creating it:

Code list	Behaviour
Producer	created automatically ("Automatically create unknown producers" toggle, on by default)
Category	matching only; creating one from `path` is possible but must be switched on (off by default)
Parameter option (SELECT/RADIO/MULTISELECT)	matching only; creating one is possible but must be switched on (off by default)
Parameter, unit, currency, warehouse, product state, VAT rate, tag, product type	matching only — never created, no matter how often it appears in the file

Why options and categories default to off

This is a deliberate safeguard against typos. If a foreign file with a misspelled category name — "Mobile Phones" instead of "Mobile phones" — created categories automatically, the catalogue would end up with dozens of near-duplicate branches after a few imports. Until you switch the toggle on, the import only warns, and you create the category/option manually the way you actually want it.

A product card (<product>) is not matched directly — it is matched through the codes of its variants. Several codes inside one <product> block must therefore belong to the same product in the database, otherwise the whole card is rejected (see the error table).

Step by step#

1. Upload and settings#

In the Eshop → Import produktů menu, click přidat (add).
Drag the file (.xml, .csv or .json) into the upload field, or click to pick it. One file per job.

Fill in the job settings:

Field	Meaning	Default
Mode	`upsert` creates and updates; `create` rejects an existing code as an error; `update` just skips an unknown code	Create and update
Match key	how a variant is looked up in the database — `code` or `ean`	Code
Default language	the language used to read texts without a `lang` attribute	`cs`
Collections (default mode)	how categories/tags/parameters/images/accessories behave when a block in the file does not say otherwise itself — `merge` (add/update) or `replace` (exactly what the file says)	Merge
Automatically create unknown producers		on
Automatically create unknown parameter options		off
Automatically create unknown categories	created from `path` only, without SEO texts	off
Stop the run on the first error	the live run stops at the first hard error of an item instead of continuing to the end of the file	off

Click Upload and continue.

File size limits: XML 100 MB, CSV/JSON 20 MB. The upload form rejects anything larger.

2. Dry-run validation (automatic)#

As soon as the file is uploaded, the system runs validation on its own and opens the job detail with the report. Nothing is written to the catalogue at this step — it is only a dry-run check.

The report summary shows:

Report line	Meaning
Will be created	new variants the import will create
Will be updated	existing variants the import will overwrite according to the file
Will be skipped	items with `action="skip"`, or `update` on a code that does not exist in the database
Will not be written (hard errors)	items with an error that blocks them completely — not written at all
Will be written incompletely (soft errors)	items that get written, but without part of their data (unknown code list, unreachable image…)

Below the summary is a paginated line log with a level filter (Errors / Warnings / Info) and a Download log link for the whole file at once. Every line carries the line number in the file, the item code, the message and — for soft errors — the value the import unsuccessfully tried to use, so you know what to add to the code list.

Hard error versus soft error

A hard error (Error level) means the item is not written at all — a malformed file, a missing or duplicate code, a matching conflict, an attempt to clear a required field. A soft error (Warning level) means the item is written, minus that one part — typically an unknown category, parameter option, warehouse, currency, state, or an unreachable image. The set is then flagged in the Sady produktů (Product sets) grid with the "Neúplný import" ("Incomplete import") badge (column Import, which also has its own filter) — so you know which cards need manual follow-up.

If the report shows errors you want to fix in the job settings (e.g. change the match key, or turn on automatic category creation), the settings form is on the same page, and after saving, the Re-validate button runs the dry-run check again. If the problem is in the file itself, fix it, delete this job and upload the file as a new one (the import cannot overwrite an already uploaded file).

The file's <settings> is only a suggestion

If the file contains its own <settings> block, the report does not ignore it, but does not apply it automatically either — the job settings always win. Differences show up in the log as info lines, so you can see when something in the file does not match what actually happens.

3. Starting the run#

Once the job is in the Validated state, the detail page shows these buttons:

Run — queues the job; cron picks it up within a minute. Use this for a file of any size.
Run now — performs the live write right in this request, up to 200 items only. Above the limit the button is hidden — use the queue instead.
Cancel — for a job that has not started running yet.
Delete — deletes the job and the uploaded file; only for jobs that are not currently running.

Both start actions write live — the confirmation dialog says so explicitly, because dev and production share one database.

4. Progress and result#

The Progress page (the Stav link in the grid and on the detail) shows a progress indicator (processed / total), running counts and the last few errors and warnings; the page refreshes itself until the run finishes. Once it is done, a second report tab appears on the job detail — the Live run report — paginated and filterable just like the dry-run report, only describing what was actually written. If "Stop the run on the first error" was on, the report says so directly — the rest of the file was not processed in that case.

5. Following up on incomplete items#

Sets flagged "Neúplný import" can be found in the Sady produktů (Product sets) grid using the Import column filter. The badge disappears:

with another clean import of the same code (with no soft errors), or
manually, in the set's edit form — a checkbox labelled "Naimportováno neúplně (vyžaduje ruční dořešení)" ("Incompletely imported — needs manual review") appears at the bottom of the form (only for sets that carry the flag); unchecking it and saving clears it.

Sample file#

The fastest way to learn what a file for your catalogue should look like is to have one generated, inspect it and edit it — the export → import roundtrip is the best way to learn the format.

In the Eshop → Produkty or Eshop → Sady produktů grid, narrow the selection with a filter (e.g. to one category), check the rows, and use the bulk action "Exportovat do XML" ("Export to XML") to download a file in exactly the import format.
Or, on the Eshop → Import produktů page, use the "Export katalogu" ("Catalogue export") form below the history table — it exports the whole catalogue (up to a safe item limit), with a choice of languages, sections (categories, texts, parameters, tags, prices, stock, images, accessories) and an "Include id" toggle — on by default, it adds id to the file so a re-import targets exactly the same card even after a code rename.
Edit the downloaded file (change prices, copy a <variant> block for a new product, delete sections you do not need) and upload it back via přidat (add) — the dry-run validation shows exactly what will happen before anything is written live.

The export only ever reads the current state of the catalogue, never writes anything. It exists as XML only (the most complete format) — there is no CSV or JSON export.

XML format#

XML is the canonical format — the only one that supports absolutely everything (including bundles and accessories). CSV and JSON are derived from it, see below.

Envelope and settings#

<import version="1.0">
  <settings>
    <mode>upsert</mode>
    <matchBy>code</matchBy>
    <defaultLang>cs</defaultLang>
    <collectionMode>merge</collectionMode>
    <autoCreateProducers>1</autoCreateProducers>
    <autoCreateOptions>0</autoCreateOptions>
    <autoCreateCategories>0</autoCreateCategories>
    <stopOnError>0</stopOnError>
  </settings>
  <products>…</products>
  <bundles>…</bundles>
</import>

version is a required attribute of the root element; only "1.0" is supported today. <settings> is entirely optional — a missing tag means the default value applies; values from the file are, in any case, only a suggestion (see above, the job settings win). <bundles> is also optional and may appear in the file even without <products>.

Value conventions#

Convention	Rule
Encoding	plain UTF-8, no BOM (a file with a BOM is rejected)
Decimal numbers	dot, canonically (`0.170`); a comma is tolerated
Date and time	`Y-m-d H:i:s` (`2026-08-16 14:30:00`), or just `Y-m-d`
Time zone	Europe/Prague
Boolean values	`1`/`0` canonically; `true`/`false` is tolerated (the `remove`/`main` attributes also accept `yes`)
Unknown tag/attribute inside a card/variant/bundle	a hard error of that item — the rest of the file is still processed
Unknown tag at `<import>`/`<settings>` level, wrong root, unsupported version	rejection of the whole file

`<product>` — the product card#

Element/attribute	Meaning
`id` (attribute)	explicit target — the numeric id of an existing card; the only way to rename a code through `<variant>` while still targeting the same card
`action` (attribute)	`create`/`update`/`upsert`/`skip` — overrides the job's mode for this card (and is inherited by variants that have no `action` of their own)
`<name lang="">`	the card's name; required in the default language for a new card
`<description lang="">`	description, recommended inside `<![CDATA[…]]>`
`<producer>`	producer name (auto-created per settings)
`<productType>`	product type (matching only)
`<activated>`	`0`/`1`, NOT NULL — an empty tag is a hard error
`<image src="">`	the card's photo, `http(s)` address only
`<categories collectionMode="">`	`<category href=""/>` or `<category path="" remove=""/>`
`<variants>`	one or more `<variant>` — a card with no variant is a hard error

`<variant>` — the sellable variant (`ProductSet`)#

Element/attribute	Meaning
`id`, `action`	same as on the card, but at variant level
`<code>`	always required, even on update — it is the matching key, max 20 characters
`<ean>`, `<isbn>`	max 45 characters, nullable (an empty tag clears it)
`<name lang="">`	required in the default language for a new variant, max 255 characters
`<longName lang="">`, `<shortDescription lang="">`, `<description lang="">`	optional texts
`<unit code="">`	unit code, defaults to `ks` if the tag is missing on a new variant
`<weight>`	kg, decimal number 0 ≤ x < 10,000,000, 3 decimal places
`<warranty>`	integer months, 0–255
`<freeDelivery>`, `<freePayment>`	`0`/`1`, default `0`
`<publishTime>`, `<unpublishTime>`	the selling window, nullable
`<activated>`	`0`/`1`, default `1`, NOT NULL
`<vat>`	VAT rate in %, matching only
`<state>`	product state, matching only
`<tags>`	`<tag remove="">Name</tag>`
`<parameters>`	see the parameters table below
`<prices>`	see prices below
`<stock warehouse="">`	see stock below
`<images>`	see images below
`<accessories>`	`<accessory code="" remove=""/>` — the code may also target a variant created in the same file; an unknown code is a soft error only (it just does not get linked)
`<links>`, `<fees>`, `<vats>`	reserved for a future version — using them is a hard error for the item

Fields that can be cleared with an empty tag (<ean/>): ean, isbn, publishTime, unpublishTime, vat, state. Fields where an empty tag is a hard error (the column is NOT NULL): code, unit, weight, warranty, freeDelivery, freePayment, activated on the variant, activated on the card. description and shortDescription are also NOT NULL, but an empty string is a legitimate value for them (clearing a description makes sense), so it is not forbidden.

Parameters#

<parameters>
  <parameter key="barva" option="cerna"/>       <!-- SELECT/RADIO by the option's internal key -->
  <parameter key="barva">Černá</parameter>       <!-- or by the option's NAME, case-insensitive -->
  <parameter key="velikosti" option="s"/>        <!-- MULTISELECT — repeat the element for more options -->
  <parameter key="velikosti" option="m"/>
  <parameter key="vaha-rozsah" value="1" value2="5"/> <!-- RANGE — value + value2 -->
  <parameter key="material">Bavlna</parameter>   <!-- TEXT/NUMBER/DATE — element content only -->
  <parameter key="stary-parametr" remove="1"/>   <!-- clears the value of this key -->
</parameters>

key is required. The shape of the value must match the parameter's type — option/text on a RANGE-type parameter, or value/value2 on a SELECT-type parameter, is a hard error for the item. An unknown parameter or unknown option is a soft error (it is simply not assigned) unless you have automatic option creation switched on.

Prices#

<prices>
  <price currency="CZK">
    <amountWithVat>25990</amountWithVat>
    <originalAmountWithVat>27990</originalAmountWithVat>
  </price>
  <price currency="CZK" fromAmount="5"><amountWithVat>24990</amountWithVat></price>
</prices>

Prices are written along currency × quantity band axes (fromAmount, an integer of 0 or more; default 0 = the base band "from 1 piece", the same way the admin price list and the catalogue export store it — 1 means the same band). For each price (current and original) choose exactly one of the pair — either the price without VAT (<amount>), or with VAT (<amountWithVat>, from which the base is worked out using the variant's rate). What gets stored is always the base without VAT, whichever of the two you send — see Price lists and VAT. Both tags of the same pair at once is a hard error — the import would not know which one wins. An unknown currency, or a <price> with no amount, is only a soft error, and that price row is skipped. The optional <points> (a non-negative integer) writes loyalty programme points.

Stock#

<stock warehouse="hlavni">
  <quantity mode="set">12</quantity>
  <minQuantity>2</minQuantity>
</stock>

warehouse is optional — if it is missing, the system must have exactly one active warehouse, otherwise the movement is not written (soft error). mode="set" sets the target physical stock (must not be negative), mode="add" adds to or subtracts from the current stock. An unknown warehouse is a soft error.

Images#

<images collectionMode="merge">
  <image src="https://example.com/img/foto-1.jpg" main="1">
    <alt>Caption</alt>
    <alt lang="en">Caption</alt>
  </image>
  <image assetId="482" remove="1"/>
</images>

src (http(s) only, otherwise a hard error) or assetId (a reference to an already uploaded file — a non-existent id is only a soft error, the image is simply not attached). Max 20 images per variant, above the limit is a hard error for the whole item.

Bundles — a discounted bundle set#

<bundles> creates and updates "bundle" sets (several items bundled together for one combined price) — with no card, variant or stock of their own.

<bundles>
  <bundle code="SET-IP16-KRYT">
    <name>iPhone 16 128 GB + free case</name>
    <activated>1</activated>
    <vat>21</vat>
    <prices>
      <price currency="CZK"><amountWithVat>25990</amountWithVat></price>
    </prices>
    <items>
      <item code="IP16-128-BLK" count="1"/>
      <item code="KRYT-IP16" count="2"/>
    </items>
  </bundle>
</bundles>

Unlike a variant, a bundle's code is an attribute, not a child element. A bundle shares texts, <tags>, <prices> and <images> with a variant — the same grammar. A bundle has no <parameters>, <stock> or <accessories> (no physical stock, no parameters of its own). <items> describes its composition — code may target anything in the database, or in the same file (a variant or another bundle), count is a required integer of 1 or more. An unknown item is a hard error for the whole bundle (unlike accessories, where it is only a soft error) — a bundle with no recognisable composition makes no sense. <items> has no collectionMode — every import overwrites the bundle's whole composition with what is in the file, even if only one <item> is missing.

Full example#

<import version="1.0">
  <settings>
    <mode>upsert</mode>
    <defaultLang>cs</defaultLang>
  </settings>
  <products>
    <product>
      <name>iPhone 16</name>
      <name lang="en">iPhone 16</name>
      <description><![CDATA[<p>Description of the whole product line…</p>]]></description>
      <producer>Apple</producer>
      <image src="https://example.com/img/iphone16-karta.jpg"/>
      <categories>
        <category href="mobilni-telefony"/>
        <category path="Elektro / Apple"/>
      </categories>
      <variants>
        <variant>
          <code>IP16-128-BLK</code>
          <ean>194253001234</ean>
          <name>iPhone 16 128 GB černý</name>
          <name lang="en">iPhone 16 128 GB Black</name>
          <shortDescription>Kompaktní vlajková loď v černé.</shortDescription>
          <unit code="ks"/>
          <weight>0.170</weight>
          <warranty>24</warranty>
          <vat>21</vat>
          <state>Novinka</state>
          <tags>
            <tag>Novinka</tag>
          </tags>
          <parameters>
            <parameter key="barva" option="cerna"/>
            <parameter key="kapacita">128 GB</parameter>
          </parameters>
          <prices>
            <price currency="CZK">
              <amountWithVat>25990</amountWithVat>
              <originalAmountWithVat>27990</originalAmountWithVat>
            </price>
            <price currency="CZK" fromAmount="5"><amountWithVat>24990</amountWithVat></price>
          </prices>
          <stock warehouse="hlavni">
            <quantity mode="set">12</quantity>
            <minQuantity>2</minQuantity>
          </stock>
          <images>
            <image src="https://example.com/img/ip16-blk-1.jpg" main="1">
              <alt>iPhone 16 black – front</alt>
              <alt lang="en">iPhone 16 Black – front</alt>
            </image>
            <image src="https://example.com/img/ip16-blk-2.jpg"/>
          </images>
          <accessories>
            <accessory code="KRYT-IP16"/>
          </accessories>
        </variant>
        <variant>
          <code>IP16-128-PNK</code>
          <name>iPhone 16 128 GB růžový</name>
          <parameters>
            <parameter key="barva" option="ruzova"/>
            <parameter key="kapacita">128 GB</parameter>
          </parameters>
          <prices>
            <price currency="CZK"><amountWithVat>25990</amountWithVat></price>
          </prices>
          <stock><quantity>4</quantity></stock>
        </variant>
      </variants>
    </product>
  </products>
</import>

Minimal example — price and stock only#

This file changes nothing else — texts, categories, parameters and images all stay as they were. The tri-state rule: what is not in the file does not change.

<import version="1.0">
  <products>
    <product>
      <variants>
        <variant>
          <code>IP16-128-BLK</code>
          <prices><price currency="CZK"><amountWithVat>23990</amountWithVat></price></prices>
          <stock><quantity>30</quantity></stock>
        </variant>
      </variants>
    </product>
  </products>
</import>

CSV format#

CSV is a flat subset of XML — quick bulk edits from a spreadsheet, 1 row = 1 variant. It cannot do bundles, accessories, code renaming or the full range of images — use XML or JSON for those.

The header is case-insensitive, the delimiter is ; (auto-detected as , when ; does not appear in the header at all), a BOM is tolerated. A file that is not valid UTF-8 is automatically converted from Windows-1250 (a common export from Czech Excel) — the conversion is noted in the log. An empty cell means "untouched" (same as a missing XML tag), the literal #NULL (case-insensitive) means "clear it".

Grouping rows into a card#

The product column groups rows that belong to one product card — any shared value works (ip16, 1, anything). Card-level columns (productName:*, productDescription:*, producer, productType, categories, productImage) are taken only from the first row of the group — on further rows they must either be empty or match the card's column, otherwise it is a structural error for that card.

Columns#

Column	Meaning
`code`	the variant's matching code (required)
`product`	groups rows into a card
`action`	`create`/`update`/`upsert`/`skip` at row level (CSV has no card-level `action`)
`name:<lang>`, `longName:<lang>`, `shortDescription:<lang>`, `description:<lang>`	variant texts
`productName:<lang>`, `productDescription:<lang>`	card texts (first row of the group only)
`ean`, `isbn`, `unit`, `weight`, `warranty`, `vat`	same meaning as in XML
`freeDelivery`, `freePayment`, `activated`	`0`/`1`
`publishTime`, `unpublishTime`	`Y-m-d H:i:s` / `Y-m-d`
`producer`, `productType`	card texts
`state`	product state
`categories`	`href` values separated by `\\|` (`href` only, no `path`)
`tags`	names separated by `\\|`
`param:<key>`	`value1\\|value2` for a multiselect, `from..to` for a range, otherwise a single value — matched exclusively by the option's name, not its internal key
`price:<CUR>`, `priceWithVat:<CUR>`	price without/with VAT in that currency — fill in only one of the pair
`originalPrice:<CUR>`, `originalPriceWithVat:<CUR>`	original price, same rule
`stock`, `stockMode`, `minQuantity`, `warehouse`	stock
`image1` … `image5`	up to 5 image URLs, `src` only, no `main`/`assetId`/alt texts
`productImage`	the card's photo

What CSV cannot do#

Missing compared to XML	Note
Bundles	`<bundles>` exists only in XML/JSON
Accessories	`<accessories>` exists only in XML/JSON
The `id` attribute	no explicit targeting, no code renaming
`action` on the card	only on a row (variant), not on the product card
Categories by `path`	`href` only, so `autoCreateCategories` never creates a new category from CSV
Price bands and user groups	always just the base band (`fromAmount=0`), no `userGroupId`
Parameter option by internal key	by name only (case-insensitive)
More than 5 images, `main`, `assetId`, alt texts	just 5 URL columns with no metadata

Example#

code;product;productName:cs;productDescription:cs;producer;categories;name:cs;name:en;shortDescription:cs;unit;weight;warranty;vat;state;tags;param:barva;param:kapacita;priceWithVat:CZK;originalPriceWithVat:CZK;price:EUR;stock;stockMode;minQuantity;warehouse;image1;image2;productImage
IP16-128-BLK;ip16;iPhone 16;"<p>Popis cele produktove rady.</p>";Apple;mobilni-telefony|elektro;iPhone 16 128 GB cerny;iPhone 16 128 GB Black;Kompaktni vlajkova lod v cerne.;ks;0.170;24;21;Novinka;Novinka;Cerna;128 GB;25990;27990;;12;set;2;hlavni;https://example.com/img/ip16-blk-1.jpg;https://example.com/img/ip16-blk-2.jpg;https://example.com/img/iphone16-karta.jpg
IP16-128-PNK;ip16;;;;;iPhone 16 128 GB ruzovy;iPhone 16 128 GB Pink;;;;;;;;Ruzova;128 GB;25990;;859.50;4;set;;;;;

The second row is a second variant of the same card (same ip16 value in the product column) — the card columns (productName:*, producer, categories) are empty there, because they are taken from the first row.

JSON format#

JSON mirrors XML — it supports absolutely everything XML does (including bundles, accessories, id, and images with assetId/main/alt texts), just written differently:

XML	JSON
element	object key
repeatable element (`<tag>`)	array of values
text with `lang` (`<name lang="en">`)	object `{"cs": "…", "en": "…"}`
text without `lang`	shorthand: a plain string (applies to the default language)
collection (default `collectionMode`)	plain array `[…]`
collection with explicit `collectionMode`	`{"mode": "merge"\\|"replace", "items": […]}`
clearing (empty tag)	`null` (for texts, also `""`)

An unknown key is just as strict an error as an unknown XML tag. The one difference from XML: the line number in the error log is not the file's actual line (JSON has none), but the item's 1-based position in its array (products[2] → line=3) — the log therefore always carries the item's code too, so items at the same position in different cards can still be told apart.

Example#

{
  "version": "1.0",
  "settings": { "mode": "upsert", "defaultLang": "cs" },
  "products": [
    {
      "name": { "cs": "iPhone 16", "en": "iPhone 16" },
      "description": { "cs": "<p>Popis cele produktove rady.</p>" },
      "producer": "Apple",
      "image": "https://example.com/img/iphone16-karta.jpg",
      "categories": [
        { "href": "mobilni-telefony" },
        { "path": "Elektro / Apple" }
      ],
      "variants": [
        {
          "code": "IP16-128-BLK",
          "ean": "194253001234",
          "name": { "cs": "iPhone 16 128 GB cerny", "en": "iPhone 16 128 GB Black" },
          "shortDescription": { "cs": "Kompaktni vlajkova lod v cerne." },
          "unit": "ks",
          "weight": 0.170,
          "warranty": 24,
          "vat": 21,
          "state": "Novinka",
          "tags": ["Novinka"],
          "parameters": [
            { "key": "barva", "option": "cerna" },
            { "key": "kapacita", "text": "128 GB" }
          ],
          "prices": [
            { "currency": "CZK", "amountWithVat": "25990", "originalAmountWithVat": "27990" },
            { "currency": "CZK", "fromAmount": 5, "amountWithVat": "24990" }
          ],
          "stock": { "quantity": 12, "mode": "set", "minQuantity": 2, "warehouse": "hlavni" },
          "images": [
            { "src": "https://example.com/img/ip16-blk-1.jpg", "main": true, "alt": { "cs": "iPhone 16 cerny - predni strana", "en": "iPhone 16 Black - front" } },
            { "src": "https://example.com/img/ip16-blk-2.jpg" }
          ],
          "accessories": ["KRYT-IP16"]
        },
        {
          "code": "IP16-128-PNK",
          "name": { "cs": "iPhone 16 128 GB ruzovy" },
          "parameters": [
            { "key": "barva", "option": "ruzova" },
            { "key": "kapacita", "text": "128 GB" }
          ],
          "prices": [
            { "currency": "CZK", "amountWithVat": "25990" }
          ],
          "stock": { "quantity": 4 }
        }
      ]
    }
  ]
}

Errors and how to fix them#

The most common report messages and what to do about them. Hard = the item is not written at all, soft = it is written minus that one part.

Message (shortened)	Type	What to do
Variant has no `<code>` / empty `<code>`	hard	the code is always required, even on update — fill it in
Code is longer than 20 characters	hard	shorten the code (the limit is fixed, a DB column)
The same matching key appears twice in the file	hard	there is a duplicate code/EAN in the file — merge the rows, or delete one
Code already belongs to another set	hard	codes are unique in the system — use a different code, or `id` for an explicit rename
Codes of one card belong to different products in the database	hard	variants inside one `<product>` must belong to the same card — split them into two cards
A new variant must have a `<name>` in the default language	hard	a name in the default language is required when creating
Field `X` cannot be cleared — the column is NOT NULL	hard	fields such as `code`, `unit`, `weight`, `activated` cannot be emptied — remove the whole tag instead of leaving it empty
Weight/warranty is out of the column's range	hard	weight 0–10,000,000 kg (3 decimal places), warranty 0–255 months
Price has both `<amount>` and `<amountWithVat>`	hard	fill in only one of the pair (without VAT, or with VAT)
Quantity band `fromAmount` must be an integer of 0 or more	hard	fix the `fromAmount` attribute value
An image/photo can only be downloaded from an `http(s)` address	hard	no `file://`, `ftp://` or relative paths
A variant has more images than the limit	hard	max 20 per variant (XML/JSON), max 5 (CSV)
Unknown tag/attribute, unknown column in the CSV header	hard (CSV: the whole file)	fix the typo in the tag/column name per the format above
Unknown producer	soft (info, when auto-create is on)	it gets created automatically, or turn on "Automatically create unknown producers"
Unknown category	soft	add the category manually, or turn on auto-create and use `path`
Unknown parameter option	soft	add the option manually, or turn on "Automatically create unknown parameter options"
Unknown currency / unknown warehouse / unknown state / unknown tag	soft	the code list is matching-only — create the value manually in the relevant admin section and import again
Image `assetId` does not exist in the database	soft	check that the id belongs to an already uploaded file
Text in language `X` is not written — missing `<name lang>`	soft	for a new translation, add the name in that language too, not just the description
Tag is reserved for a future version	hard	`<links>`, `<fees>`, `<vats>` are not yet supported — remove them from the file
Unknown bundle item	hard (the whole bundle)	the code inside `<items>` must exist in the database or elsewhere in the same file

Automatic run#

The Run button queues the job — it is picked up by the /cron/eshop/product-import/run cron job, which runs every minute and always takes only the oldest job waiting in the queue. For details on scheduled jobs and how cron is run, see the Scheduled jobs chapter.

Statistics#

The Eshop → Import produktů → Statistiky page shows a summary of runs over a chosen period (7/30/90 days): job counts by state, totals of created/updated/ skipped/failed items, a "Runs over time" chart, and a table of recent runs linking to their detail.

Limitations#

Limitation	Value
XML file size	100 MB
CSV/JSON file size	20 MB
Single image size	10 MB
Images per variant	20 (XML/JSON), 5 (CSV)
"Run now" (synchronous run)	up to 200 items only
CSV	cannot do bundles, accessories, `id`, categories by `path`, price bands, options by internal key
Bundles	no stock, parameters or accessories — just texts, activation, VAT, tags, prices, images and composition
Images in general	only downloaded from `http(s)` addresses; files are stored keyed by URL, so the same address uploaded more than once is not duplicated

Product import#

What the import does and does not do#

Step by step#

1. Upload and settings#

2. Dry-run validation (automatic)#

3. Starting the run#

4. Progress and result#

5. Following up on incomplete items#

Sample file#

XML format#

Envelope and settings#

Value conventions#

<product> — the product card#

<variant> — the sellable variant (ProductSet)#

Parameters#

Prices#

Stock#

Images#

Bundles — a discounted bundle set#

Full example#

Minimal example — price and stock only#

CSV format#

Grouping rows into a card#

Columns#

What CSV cannot do#

Example#

JSON format#

Example#

Errors and how to fix them#

Automatic run#

Statistics#

Limitations#

`<product>` — the product card#

`<variant>` — the sellable variant (`ProductSet`)#