¶ Item import (xml) - transfer in Hummerce

Item import (xml) is a transfer in the Hummerce panel that lets store staff exchange catalog data - items, categories, prices, availability and properties - via an XML file, as an alternative to the item transfer in Excel format. The XML format is a good fit for file-based integrations and for data that isn't conveniently described in a spreadsheet (e.g. a property with multiple values, or values that differ per store view).

Last updated: 2026-09-29. The transfer is part of the platform's core transfer mechanism - available in all current store versions.

¶ Benefits and use cases

Import and export items, their categories, prices, availability, and properties in a single XML file - without manually editing each item in the panel.
The format suits file-based integrations with external systems (e.g. an ERP or a data warehouse) that generate data in XML rather than Excel.
One file entry supports multiple values of the same property (e.g. an item's trait list) and values that differ per store view - something a spreadsheet doesn't describe conveniently.
A new item is created automatically if the symbol from the file doesn't exist in the store yet - the transfer doesn't require creating the item in the panel first.
Matching a category, producer, or item group can go by a custom _transfer property instead of the symbol - useful when an external system uses different symbols than Hummerce.

¶ How it works

¶ What the file can carry

Item symbol - a mandatory field; the store recognizes the item by it. A symbol not in the store creates a new item.
Name - a separate value for each store language.
Main category - the category's symbol; a category that doesn't exist yet is created under the main category. Import doesn't remove the item's existing visibility in other categories.
Article - the symbol of the parent item, when the item being transferred is a sub-item (variant).
Price, currency, tax rate - according to the currencies and tax rates defined in the store; the price is saved net or gross, depending on the store's or item's current setting.
Producer and item group - matched by symbol, or, if the producer/group has the _transfer property set, by that property (it takes precedence over the symbol).
Available, Visible, Buyable - boolean values (yes/no).
Any other item property - as separate entries in the file, with the option to specify the language and view a value applies to.

¶ Structure of the XML file

The file is a list of objects - items - each in its own tag with a symbol and creation/modification dates. Inside an object:

attributes - individual item fields (e.g. visibility, category, price, producer),
properties (property) - item property values, with an optional language (locale) and view (view); a property with multiple values (e.g. a trait list) is saved as consecutive value tags,
views - the list of views the item should be assigned to, with an add, override, or remove mode.

Shortened example:

<extension>
  <object target="item" symbol="larch-cone" modified="2019-04-05 00:03:02" created="2014-12-28 23:54:52">
    <attribute name="visible" value="true" />
    <attribute name="category" value="cones" />
    <attribute name="producer" value="zielony-las" />
    <attribute name="price" value="39.00 PLN @ (23.00)" />
    <property symbol="_name" locale="pl">Szyszka modrzewiowa</property>
    <property symbol="_name" locale="en">Larch cone</property>
    <views updateMode="ADD">
      <view>default</view>
    </views>
  </object>
</extension>

This same format (the extension tag with object elements) also drives the Property types (xml), Location tree import (xml), and Static pages (xml) transfers - only the object kind (target) and the list of available fields differ. Common rules for all transfers (test mode, background processing, ignore errors) are described in Data transfer.

¶ Version

The item transfer in XML format is part of the platform's core transfer mechanism - available in all current store versions.

¶ Dependencies

An XML file in the format matching this transfer - prepared by an external system (e.g. an ERP or a data warehouse), or exported from the store itself as a template.
Currencies and tax rates used in the file must already be configured in the store.
General data transfer rules - Data transfer.

¶ Implementation

The basic format works out of the box, no implementation needed - the transfer is part of the platform standard.
Adapting to a non-standard file (a different field layout than the platform standard, a file from an external customer system) requires implementation - the scope and time are quoted individually after analyzing a sample file.

¶ Limitations

The XML file is prepared outside the panel - the transfer has no wizard or file-structure preview, only import and export of a ready document.
Import sets the item's main category, but doesn't remove its visibility in the other categories it was assigned to outside the file.
We do not verify the task for legal compliance (e.g. licenses of submitted materials, GDPR, store terms of service).

¶ Future development

A wizard or preview of the XML file's content in the panel, without having to prepare it outside the store.
Clearer error messages pointing to the exact location of a file error during import.

¶ Frequently asked questions

How does the XML transfer differ from the Excel transfer for items?
Both move items, prices, and properties. XML handles multi-value properties and values that differ per store view better; Excel is more convenient for manual editing. See Item import and export (xls).

Can the XML file create a new item?
Yes, if the symbol from the file doesn't exist in the store yet.

Does import remove the item's visibility in other categories?
No. Import sets the main category, but doesn't remove the item's existing visibility in the other categories.

Can the transfer be tested before changes are saved?
Yes, like every transfer in Hummerce - test mode checks the file and rolls back the changes, without saving anything in the store. See Data transfer.

Can matching a category or producer be based on a field other than the symbol?
Yes, through the _transfer property set on the category, producer, or item group - it then takes precedence over the symbol.

Data transfer - the list of transfers and common rules (test mode, background processing, reports).
Item import and export (xls) - the same data scope in Excel format.
AI assistant - MCP server - import and export of the same XML format also available as assistant tools.

Want to automate updating your catalog from an XML file generated by your own system? Contact the Hummerce team (in Polish).

¶ Configuration details

¶ Access in the admin panel

Running the transfer: the Data transfer -> Items (xml) menu - choice of direction (import/export), file, test mode, and the other options common to transfers (Data transfer).

¶ REST API and MCP

MCP (AI assistant - MCP server):
- ec2_extension_xml_write - generates an XML file in this format for the given items (and other catalog objects),
- ec2_extension_xml_import - imports such an XML file into the store,
- ec2_transfer_xml_spec - returns the full grammar of the XML format (and the property format) to the AI assistant, so it can build a valid file on its own.

¶ Parameters

Field in the transfer	Element/attribute in XML
Symbol	attribute `symbol`
Name (per language)	`property symbol="_name"` with a `locale` attribute
Main category	attribute `category`
Article (parent item)	attribute `article`
Price	attribute `price`
Producer	attribute `producer`
Item group	attribute `itemGroup`
Available	attribute `available`
Visible	attribute `visible`
Buyable	attribute `buyable`
Matching by a field other than the symbol	property `_transfer` (on the category, producer, or item group)