ICML format allows to upload technical information on items into the system (ID and XML ID of items, information on leftover stock), and also the complicated structure of catalogs with offers (SKU). You can generate the uploading file yourself on the side of web-store according to description below. For number of CMS there are ready-made integration modules, which can generate ICML with catalog.
<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2013-06-20 10:09:18">
<shop>
<name>Web-store</name>
<company>Web-store</company>
<categories>
<category id="2">Office furniture</category>
<category id="3" parentId="2">
<name>Shelvings</name>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6589.JPG</picture>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6590.JPG</picture>
</category>
<category id="4" parentId="2">Workplaces</category>
<category id="5" parentId="2">Chairs and armchairs</category>
<category id="6">Cushioned furniture</category>
<category id="7" parentId="6">Sofas</category>
<category id="8" parentId="6">Beds</category>
<category id="9">Garden furniture</category>
<category id="10">Mirrors</category>
<category id="11">Lighting</category>
<category id="12">Textile</category>
</categories>
<offers>
<offer id="115" productId="43" quantity="16">
<url>http://testbitrix.test/catalog/shelves/rack_2_sectional/</url>
<price>14000.00</price>
<purchasePrice>13200.00</purchasePrice>
<categoryId>3</categoryId>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6589.JPG</picture>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6590.JPG</picture>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6591.JPG</picture>
<name>Shelving with 2 sections</name>
<xmlId>82</xmlId>
<productName>Shelving with 2 sections</productName>
<param name="Vendor code" code="article">789789</param>
<param name="Size" code="size">two-tier</param>
<param name="Color" code="color">white</param>
<vendor>Abagure</vendor>
<param name="Weight" code="weight">50 kg</param>
<unit code="pcs" name="Piece" sym="pcs." />
<vatRate>18</vatRate>
<dimensions>100/50.8/150</dimensions>
<barcode>012485ab</barcode>
<markable>Y</markable>
</offer>
<offer id="116" productId="43" quantity="25">
<url>http://testbitrix.test/catalog/shelves/rack_2_sectional/</url>
<price>14500.00</price>
<purchasePrice>11000.00</purchasePrice>
<categoryId>3</categoryId>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec1501.JPG</picture>
<name>Shelving with 2 sections (orange)</name>
<xmlId>83</xmlId>
<productName>Shelving with 2 sections</productName>
<param name="Vendor code" code="article">789789</param>
<param name="Size" code="size">two-tier</param>
<param name="Color" code="color">black</param>
<vendor>Cologio</vendor>
<param name="Weight" code="weight">60 kg</param>
<unit code="pcs" name="Piece" sym="pcs." />
<vatRate>none</vatRate>
<dimensions>100/50.8/150</dimensions>
<barcode>012485ab</barcode>
<markable>Y</markable>
</offer>
<offer id="253" productId="155" quantity="20">
<url>http://testbitrix.loc/catalog/textile/sheet_beige/</url>
<price>200.00</price>
<purchasePrice>175.00</purchasePrice>
<categoryId>12</categoryId>
<picture>http://testbitrix.loc/upload/iblock/be7/be7139e39cda62e8c032f3b2ed0106e4.JPG</picture>
<name>Linen cloth</name>
<xmlId>66</xmlId>
<productName>Linen cloth</productName>
<param name="Vendor code" code="article">151642</param>
<param name="Width" code="width">150</param>
<param name="Color" code="color">beige</param>
<param name="Weight" code="weight">2.05</param>
<unit code="meter" name="Meter" sym="m" />
<vatRate>10</vatRate>
<markable>Y</markable>
</offer>
<offer id="56" productId="56" quantity="30">
<productActivity>N</productActivity>
<url>http://testbitrix.loc/catalog/summer_collection/rocker/</url>
<price>4250.00</price>
<categoryId>9</categoryId>
<picture>http://testbitrix.loc/upload/iblock/68b/68b955690e0f1f9dacb96cc4248e9c44.jpg</picture>
<name>Rocking chair</name>
<xmlId>104</xmlId>
<productName>Rocking chair</productName>
<param name="Vendor code" code="article">891081</param>
<vendor>Riotto</vendor>
<unit code="pcs" name="Piece" sym="pcs." />
</offer>
</offers>
</shop>
</yml_catalog>
<?xml version="1.0" encoding="..."?>
ICML-file is the XML-document, in the beginning should be located XML-header, for example, <?xml version="1.0" encoding="UTF-8"?>
. For the encoding it is recommended to use UTF-8.
<yml_catalog date="2013-08-08 17:00">
<shop>
...
</shop>
</yml_catalog>
As the root element in ICML format is used the element <yml_catalog>
. In one file can be only one such element. The tag has one mandatory attribute date
, its value should match date and time of file generation. For storage and transfer several catalogs it is recommended to use several similar xml-documents.
<shop>
<name>My web-store</name>
<company>My company</company>
<categories> … </categories>
<offers> … </offers>
</shop>
Element <shop>
contains description of web-store and catalog.
The store is described by the following elements:
<name>
— web-store name; Maximum length is 255 symbols;
<company>
— company name;
<categories>
— container with items categories;
<offers>
— container with description of all items in store.
The elements should not be duplicated.
<categories>
<category id="2">Office furniture</category>
<category id="3" parentId="2">
<name>Shelvings</name>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6589.JPG</picture>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6590.JPG</picture>
</category>
<category id="4" parentId="2">Workplaces</category>
<category id="5" parentId="2">Chairs and armchairs</category>
<category id="6">Cushioned furniture</category>
<category id="7" parentId="6">Sofas</category>
<category id="8" parentId="6">Beds</category>
<category id="9">Garden furniture</category>
<category id="10">Mirrors</category>
<category id="11">Lighting</category>
<category id="12">Textile</category>
</categories>
In element <categories>
there is list of items categories. Element <category>
describes one separate category and contains its name. The name should not exceed 255 symbols. Each element must have the attribute id
, category id, it should be a unique sequence of symbols not more than 255 symbols. Also each element <category>
should contain the attribute parentId
parental category id, its value should be equal with one of existing categories. This attribute allows to describe the inserted structure of catalog. If item category description does not contain the attribute parentId, then the category is considered to be the root.
Also, the category can be described by the following elements:
<name>
— category name, the maximum length is 255 characters.
<picture>
— URL of category picture. The tag can be repeated. The maximum length of the link is 2000 characters.
<offers>
<offer> … </offer>
…
</offers>
Element <offers>
contains the list of web-store items and offers. Each element <offer>
describes item and the offer. Element <offers>
must be one, and elements <offer>
can be as much as desired.
<offer id="115" productId="43" quantity="16">
<url>http://testbitrix.test/catalog/shelves/rack_2_sectional/</url>
<price>14000.00</price>
<purchasePrice>13200.00</purchasePrice>
<categoryId>3</categoryId>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6589.JPG</picture>
<picture>http://testbitrix.test/upload/iblock/d2b/d2b25cbdc1f76b8b1672f5e8d1ec6590.JPG</picture>
<name>Shelving with 2 sections</name>
<xmlId>82</xmlId>
<productName>Shelving with 2 sections</productName>
<param name="Vendor code" code="article">789789</param>
<param name="Size" code="size">two-tier</param>
<param name="Color" code="color">white</param>
<vendor>Riotto</vendor>
<param name="Weight" code="weight">50 kg</param>
<unit code="pcs" name="Piece" sym="pcs." />
<vatRate>none</vatRate>
<dimensions>100/50.8/150</dimensions>
<weight>50</weight>
<barcode>012485ab</barcode>
<markable>Y</markable>
</offer>
Element <offer>
contains the fields, describing properties either of item or offer, that allows for element <offer>
to be either item or offer. Element contains mandatory attributes id
and productId
, which match the offer or item id. If there are no offers in web-store, then id can be the same. id
and productId
must not be longer than 255 symbols.
Pay attention that offer id must be unique. If to copy item id to the offer id when generating, then this id can match another offer id. It may lead to irreparable consequences.
<!-- Offer id conflict. -->
<offer id="115" productId="43" quantity="16"> … </offer>
<offer id="115" productId="115" quantity="18"> … </offer>
Element <offer>
may consist the attribute quantity
, which matches item (offer) quantity at the warehouse. For each offer the quantity can be different. Quantity has to be the whole or fractional number up to 3 signs after a comma, in the range from 0 to 99 999 999.
Offer (item) can be desribed by the following elements:
<productActivity>
— index of item activity, element is not mandatory. If the element is absent, the item is considered to be active; For inactive item it is necessary to transfer N
, in the rest cases you can transfer Y
or skip this element; For item deactivation it is necessary to specify this element for all offers of this item; Separate offers can not be deactivated;
<url>
— offer (item) page in web-store. It is important to specify the correct protocol (http://
or https://
) and domain (with www
or without). This URL is used for definition of items, which have been watched by customer, within integration with Google Analytics; Maximum length of link is 2000 symbols;
<price>
— offer (item) price; Price can be whole or fractional number up to 2 signs after a comma, in range from 0 to 99 999 999;
<purchasePrice>
— offer (item) purchasing price, it is not mandatory; If there is no tag in the file, the value will not be reset; Purchased price can be whole or fractional number up to 2 signs after a comma, in range from 0 to 99 999 999;
<categoryId>
— category id, to which is belong offer (item), the value should be one of category id. If offer (item) belongs to several categories, there can be several such elements;
<picture>
— URL of offer (item) picture, the tag can be repeated, it is not mandatory. It is used for displaying picture preview. You may specify pictures in jpg or png-format, the size is not more than 2Mb. It is important to specify the correct protocol (http://
or https://
) and domain (with www
or without), otherwise system will not be able to show items preview; Maximum length of link is 2000 symbols;
<name>
— offer name; Maximum length is 255 symbols;
<productName>
— item name; Maximum length is 255 symbols;
<xmlId>
— item external id, the element is not mandatory. If web-store uses catalog uploading from warehouse system, then the value of this element matches item id in that system; This field is a sequence of symbols not longer than 255 symbols;
<param name="..." code="...">
— item parameter, where:
name
— item parameter name;
code
— alphanumeric code of parameter, permissible symbols: a-Z0-9_
, other symbols can be cut
example: color
, size
. Maximum code length is 50 symbols. Read also parameters with special handling.
The length of item property can not exceed 255 symbols.
<vendor>
— item manufacturer, the element is not mandatory; Maximum length is 255 symbols;
<unit>
- measurement unit of a product, the element is not necessary;
code
- alphabetic-numeric code of measurement unit, available symbols: a-Z0-9_-
, the first symbol should be a-z
; Maximum length is 255 symbols;
name
- full measurement unit name, optional element - in case of absence, when creating, code is taken as the name, not necessary for existing measurement unit forwarding; Maximum length is 255 symbols;
sym
- short measurement unit name, optional element - in case of absence, when creating, code is taken as the short name, not necessary for existing measurement unit forwarding; Maximum length is 5 symbols;
<vatRate>
- VAT rate on item in percentage; Use none
for transferring the "Without VAT" value; the element is not mandatory;
<dimensions>
are product dimensions in length, width and height format. The unit of every dimension is centimeter. Format is three positive numbers accurate to a thousandth (0.001), the separator of the integer and fractional part is the point. Numbers need to be separated by symbol "/" without gaps. The value is automatically rounded to the third sign in the fractional part when you specify higher accuracy. The maximum allowable value is 999 999 999 cm. Dimensions will be converted in ml when catalogue is loaded because the unit of dimensions is ml in the system.
<weight>
is product weight. The unit is kg. Format is the positive number accurate to 0.001 (or 0.000001 depends on “weight accuracy” setting: grams or milligrams). The separator of the integer and fractional part is the point. The maximum allowable value is 9 999 999 kg. Weight will be converted in gram when catalogue is loaded because this is the unit of weight.
Note: weight can be specified by this element and by the parameter with special handling <param name="weight" code="weight"></param>
. The last one was left for reverse compatibility. The last value will be applied if product weight is specified at the same time by the element and the parameter. It is possible to specify the measurement unit of weight for the parameter, but the measurement unit for this element is kg by default.
<barcode>
is product barcode. It can be specified by this element and by the parameter with special handling <param name="barcode" code="barcode"></param>
. Format is the string that contains only digits and latin letters. Maximum length is 255 symbols.
<markable>
- is a parameter indicating that the product should be marked. If the product is subject to marking, pass Y
, otherwise pass N
or omit the element. If this parameter is different for the trade offers of the same product, the value from the last trade offer will be used.
The value of element <xmlId>
is used when exchanging of items data and orders data between system and the warehouse system.
In the list there are code
of parameters, which have the special handling in system:
article
— offer vendor code. Random string;
weight
— offer weight in gramms. Weight in gramms can be whole or fractional number up to 3 signs after a comma, in range from 0 to 9 999 999 999;
description
— offer description;
barcode
— offer barcode.
<param name="Weight" code="weight">50</param>
It is also permitted to specify weight with short names of units (g, kg, t)
<param name="Weight" code="weight">1.02 kg</param>
<param name="Weight" code="weight">0.2 t</param>
when downloading the catalog, weight will be transferred to gramms, since the gram is the weight unit in system.