The ICML format is an extension of the YML format. It allows to upload technical information about products to the system (ID and XML ID of products, information about stock balances), as well as a complex structure of catalogs with trade offers (SKU). You can generate the upload file yourself on the side of your online store as described below. For a number of CMS there are ready-made integration modules that can generate ICML with a catalog of products.
Format description
<?xml version="1.0" encoding="UTF-8"?><yml_catalog date="2013-06-20 10:09:18">
<shop>
<name>Online store</name>
<company>Online store</company>
<categories>
<category id="2">Office furniture</category>
<category id="3" parentId="2">
<name>Racks</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">Workplace</category>
<category id="5" parentId="2">Chairs and armchairs</category>
<category id="6">Soft furniture</category>
<category id="7" parentId="6">Sofas</category>
<category id="8" parentId="6">Beds</category>
<category id="9">Farden furniture</category>
<category id="10">Mirrors</category>
<category id="11">Lightening</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>2-section rack</name>
<xmlId>82</xmlId>
<productName>2-section rack</productName>
<param name="Article" code="article">789789</param>
<param name="Size" code="size">two-tier</param>
<param name="Colour" code="color">white</param>
<vendor>Abagure</vendor>
<param name="Weight" code="weight">50</param>
<unit code="pcs" name="Piece" sym="pc." />
<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>2-section rack (orange)</name>
<xmlId>83</xmlId>
<productName>2 -section rack</productName>
<param name="Article" code="article">789789</param>
<param name="Size" code="size">two-tier</param>
<param name="Colour" code="color">черный</param>
<vendor>Cologio</vendor>
<param name="Weight" code="weight">60</param>
<unit code="pcs" name="Piece" sym="pc." />
<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>Beige linen fabric</name>
<xmlId>66</xmlId>
<productName>Beige linen fabric</productName>
<param name="Article" code="article">151642</param>
<param name="Width" code="width">150</param>
<param name="Colour" code="color">beige</param>
<unit code="meter" name="Meter" sym="м" />
<vatRate>10</vatRate>
<weight>2.05</weight>
</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="Article" code="article">891081</param>
<vendor>Riotto</vendor>
<unit code="pcs" name="Piece" sym="pc." />
</offer>
</offers>
</shop>
</yml_catalog>XML header
<?xml version="1.0" encoding="..."?>An ICML file is an XML document and must be preceded by an XML header, eg <?xml version="1.0" encoding="UTF-8"?>. It is recommended to use UTF-8 as encoding.
Element <yml_catalog>
<yml_catalog date="2013-08-08 17:00">
<shop>
...
</shop>
</yml_catalog>The <yml_catalog> element is used as the ICML root element. There can be only one such element in one file. The tag has one required attribute date, the value of which must match the date and time the file was generated. To store and transfer several directories, we recommend using several similar xml documents.
Element <shop>
<shop>
<name>Мой интернет-магазин</name>
<company>Моя компания</company>
<categories>… </categories>
<offers>… </offers>
</shop>
```
The `<shop>` element contains a description of the online store and product catalog. The store is described by the following elements:
`<name>` - the name of the online store; Maximum length 255 characters;
`<company>` - company name;
`<categories>` - a container that contains categories of goods;
`<offers>` - a container that contains descriptions of all products of the online store.
All elements must not be duplicated.
### Element `<categories>`
```php
<categories>
<category id="2">Офисная мебель</category>
<category id="3" parentId="2">
<name>Стеллажи</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">Рабочие места</category>
<category id="5" parentId="2">Стулья и кресла</category>
<category id="6">Мягкая мебель</category>
<category id="7" parentId="6">Диваны</category>
<category id="8" parentId="6">Кровати</category>
<category id="9">Мебель для сада</category>
<category id="10">Зеркала</category>
<category id="11">Освещение</category>
<category id="12">Текстиль</category>
</categories>
```
The `<categories>` element contains a list of product categories for the online store. The `<category>` element describes one single category and contains its name. The name should not exceed 255 characters. Each element must have the attribute `id` - category identifier, it must be a unique sequence of characters no longer than 255 characters. Also, each element `<category>` can contain the attribute `parentId` - the identifier of the parent category, its value must be one of the identifiers of existing categories. This attribute allows you to describe the nested directory structure. If the description of a product category does not contain the parentId attribute, the category is considered root. Also, a category can be described by the following elements:
* `<name>` - category name, maximum length 255 characters.
* `<picture>` - URL of the category picture. The tag can be repeated. The maximum link length is 2000 characters.
### Element
```php
<offers>
<offer>… </offer>
…
</offers>The <offers> element contains a list of products and product offers of the online store. Each element <offer> describes a product and offer. The <offers> element must be unique, and the <offer> elements can be as many as you like.
Element <offer>
<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>Стеллаж 2-х секционный</name>
<xmlId>82</xmlId>
<productName>Стеллаж 2-х секционный</productName>
<param name="Артикул" code="article">789789</param>
<param name="Размер" code="size">двухъярусная</param>
<param name="Цвет" code="color">белый</param>
<vendor>Riotto</vendor>
<param name="Вес" code="weight">50</param>
<unit code="pcs" name="Штука" sym="шт." />
<vatRate>none</vatRate>
<dimensions>100/50.8/150</dimensions>
<weight>50</weight>
<barcode>012485ab</barcode>
<markable>Y</markable>
</offer>
```
The `<offer>` element contains fields describing the properties of both the product and the offer, which enables the `<offer>` element to be both a product and a trade offer. The element contains the required attributes `id` (external ID of the trade proposal in the system) and `productId`, which correspond to the ID of the trade proposal and the product. If there are no trade offers in the online store, then the identifiers may coincide. `id` and `productId` must be no longer than 255 characters. Please note that the trade proposal identifier must be unique, and if, during generation, the product identifier is copied into the trade proposal identifier, then the identifier may coincide with the identifier of another trade proposal, this can lead to irreparable consequences.
```php
<!-- Конфликт идентификаторов торговых предложений. -->
<offer id="115" productId="43" quantity="16">… </offer>
<offer id="115" productId="115" quantity="18">… </offer>The <offer> element may contain the quantity attribute, which corresponds to the quantity of an item (trade offer). Each trade offer may have its own number. The number must be an integer or fractional number with precision up to 3 decimal places, in the range from 0 to 99,999,999.
A trade offer (product) is described by the following elements: <productActivity> - an indicator of the product's activity, the element is optional, if the element is absent, the product is considered active; For an inactive product, you must send N, in other cases you can send Y or omit the element; To deactivate a product, you must indicate this element for all product offers of this product; Individual product offers cannot be deactivated; '' 'Please note' '' that if a product has an inactive trade offer, then the product and all trade offers are considered inactive.
<url> - the page of the trade offer (product) in the online store. It is important to specify the correct protocol (http:// or https://) and domain (with or without www). This URL is used to determine the products viewed by the customer within the [[Users / GoogleAnalytics | integration with Google Analytics]]; The maximum link length is 2000 characters;
<price> - the price of the trade offer (goods); The price can be whole or fractional with an accuracy of up to 2 decimal places in the range from 0 to 99,999,999;
<purchasePrice> - the purchase price of the trade offer (goods), is optional; If there is no tag in the file, the value will not be reset; The purchase price can be whole or fractional with an accuracy of 2 decimal places in the range from 0 to 99,999,999;
<categoryId> - identifier of the category to which the trade proposal (product) belongs; the value must be one of the category identifiers, if the trade proposal (product) is in several categories, then there may be several such elements;
<picture> - URL of the trade offer (product) picture, the tag can be repeated, it is not required. Used to display preview images. You can specify images in jpg, png format no more than 2MB in size. It is important to specify the correct protocol (http:// or https://) and domain (with or without www), otherwise the system will not be able to display product previews. It is also important that the link to the product is direct and no redirects are made when you go to it. The maximum link length is 2000 characters;
<name> - the name of the trade offer; Maximum length 255 characters;
<productName> - product name; Maximum length 255 characters;
<xmlId> - external identifier of the product, the element is optional - if the online store uses unloading of the range of goods from the warehouse system (1C, MoySklad), then the value of this element corresponds to the identifier of the product in this system; The field is a sequence of characters no more than 255;
<param name="..." code="..."> - item parameter, where:
name - product parameter name; Maximum length 255 characters;
code - alphanumeric parameter code, allowed characters: a-Z0-9_, other characters will be cut off eg: color, size. The maximum code length is 50 characters. See also [[# offer-param-special | parameters with special treatment]]. The length of a product property value must not exceed 255 characters.
<vendor> - product manufacturer, the element is optional; Maximum length 255 characters;
<unit> - unit of measure for the item, the element is optional;
code - alphanumeric code of the unit of measure, allowed characters: a-Z0-9_-, the first character must be a-z; Maximum length 255 characters;
name - full name of the unit of measure, optional element - if absent, when creating, the code is taken as the name, for the existing unit of measure it is not required to transfer; Maximum length 255 characters;
sym - short name of the unit of measure, optional element - if absent, when creating, the code is taken as a short name, for the existing unit of measure it is not required to transfer; The maximum length is 5 characters;
<vatRate> - The rate of value added tax (VAT) for the product in percent; To transfer the value "Without VAT" use none; the element is optional;
<dimensions> - Product dimensions in Length / Width / Height format. The unit of measurement for each dimension is centimeter. Format: three positive numbers up to thousandths (0.001), decimal point separator. Numbers must be separated by "/" without spaces. If you specify a higher precision, the value is automatically rounded to the third decimal place (inclusive) in the fractional part. The maximum allowable value is 999 999 999 cm. When loading the catalog, the dimensions will be converted into millimeters, since the unit of dimensions in the system is millimeters.
<weight> - Item weight. The unit of measurement is kilogram. Format: a positive number with an accuracy of 0.001 (or 0.000001, depending on the CRM setting "Weight accuracy": grams or milligrams, respectively), the separator of the integer and fractional parts is a period. If you specify a higher precision, the value is automatically rounded to the third decimal place (inclusive) in the fractional part. The maximum allowable value is 9,999,999 kg. When loading the catalog, the weight will be converted to grams, since the unit of weight in the system is grams. '''Note'''. The weight can be specified both using this element and using the parameter with special handling <param name="Вес" code="weight"></param>. The latter was retained for backward compatibility. If the weight for the same product is specified both with the element and with the parameter, then the last found value will be taken. Also note that for a parameter it is possible to indicate the unit of weight measurement, for the same element (<weight>) the unit of measurement is always kilogram, and it is not necessary to indicate it.
<barcode> - Product barcode. Can be specified using this element or using a parameter with special handling <param name="Штрих-код" code="barcode"></param>. Format: a string of up to 255 characters inclusive, consisting only of numbers and Latin letters.
<markable> - flag of the need to mark the goods. If the product is to be marked, you must send Y, otherwise you must send N or omit the element. If this feature differs for trade offers of the same product, then the value from the last trade offer will be set.
The value of the <xmlId> element is used when exchanging data on goods and orders with the warehouse system (1C, MyStore).
Parameters with special treatment
The list contains code parameters that have special handling in the system:
article - trade offer article; An arbitrary string;
weight - the weight of the offer in grams; The weight converted to grams must be an integer or fractional number with an accuracy of 3 decimal places in the range from 0 to 9 999 999 999;
description - description of the trade offer;
barcode - trade offer barcode.
Note that the description field is not displayed on the system. It can be used in [[Developers / Twig | twig templates]]. For example, for output in printed forms.
<param name="Вес" code="weight">50</param>it is also allowed to indicate weight values with indication of abbreviated weight units (g, q, t)
<param name="Вес" code="weight">1.02</param>
<param name="Вес" code="weight">0.2 т</param>when loading the catalog, the weight will be converted to grams, since the unit of weight measurement in the system is grams.