YML feed requirements

Goods list

General requirements for product feeds:

Each product must have a unique ID.
The IDs of the same product must be the same in different feeds, even when the feeds have different types. For example, the same product should have the same ID in your Yandex Market and Google Shopping feeds both.

To learn more about the YML format for the Yandex Market feed, see Yandex Market Help.

Any XML document may contain only one root element. The YML format uses the <yml_catalog> element as the root element. The date attribute of the <yml_catalog> element should correspond to the date and time the YML file was generated on the advertiser's side. The date must be in YYYY-MM-DD hh:mm format.

The list of the advertiser's product offerings is contained in the <offers> element. Each product offering is described in a separate <offer>element. Add the <currencies> and <categories> elements in the <shop> element before the list of product offers. To learn more about elements included in <shop>, see Yandex Market Help.

Offer description types

There are two types of offer description: simplified and custom. These description types differ only in how you pass the product name:

In simplified offers, the product name is passed in a single <name> element.
In custom offers, the product name is passed in three elements: <typePrefix>, <vendor>, and <model>.

You can also use a combined description type and use elements from both the simplified and custom types. The advantage here is that you have more elements for generating a relevant ad.

Simplified type	Custom type	Combined type
`<name>`Smartphone Samsung Galaxy S22 Ultra 8/128 GB, blue`</name>`	`<typePrefix>`Smartphone`</typePrefix>` `<vendor>`Samsung`</vendor>` `<model>`Galaxy S22 Ultra 8/128 GB, blue`</model>`	`<name>`Smartphone Samsung Galaxy S22 Ultra 8/128 GB, blue`</name>` `<typePrefix>`Smartphone`</typePrefix>` `<vendor>`Samsung`</vendor>` `<model>`Galaxy S22 Ultra 8/128 GB, blue`</model>`

Simplified and custom offers can coexist within the same feed.

Offer examples

Simplified description

Custom description (vendor.model)

This is the basic, simpler type of description.

Example:

  <offer id="0123456" available="true">
    <url>http://www.надежнаятехника.рф/catalog/element/index.php?from=ya_market&utm_source=ya_market&utm_medium=cpc</url>
    <price>1620.00</price>
    <oldprice>1800.00</oldprice>
    <currencyId>RUB</currencyId>
    <categoryId>19</categoryId>
    <picture>http://89.123.45.678/catalog/photo/19/6.JPG</picture>
    <picture>http://89.123.45.678/catalog/photo/19/7.JPG</picture>
    <store>false</store>
    <pickup>true</pickup>
    <delivery>false</delivery>
    <name>Антивирус ESET NOD32 Platinum Edition</name>
    <vendor>Eset</vendor>
    <vendorCode>NOD32-ENA-NS(BOX)-2-1</vendorCode>
    <description>Антивирус ESET NOD32 Platinum Edition - лицензия на 2 года NOD32-ENA-NS(BOX)-2-1</description>
    <video>http://89.123.45.678/catalog/video/19/6.MP4</video>
    <sales_notes>Оплата: Наличные, Б/Н, пластиковые карты, кредит</sales_notes>
    <manufacturer_warranty>true</manufacturer_warranty>
    <country_of_origin>Россия</country_of_origin>
    <age unit="year">18</age>
  </offer>

This type of description is practical and versatile. It's recommended you use it for describing products in most categories.

Example:

  <offer id="1234567" type="vendor.model" available="true">
    <url>http://www.надежнаятехника.рф/catalog/element/index.php?from=ya_market&utm_source=ya_market&utm_medium=cpc</url>
    <price>889.00</price>
    <oldprice>17000.00</oldprice>
    <currencyId>RUR</currencyId>
    <categoryId>1111</categoryId>
    <picture>http://89.123.45.678/catalog/photo/19/6.JPG</picture>
    <picture>http://89.123.45.678/catalog/photo/19/7.JPG</picture>
    <store>false</store>
    <pickup>false</pickup>
    <delivery>true</delivery>
    <typePrefix>Принтер</typePrefix>
    <vendor>НP</vendor>
    <model>Deskjet D2663</model>
    <description>Серия принтеров для людей, которым нужен надежный, простой в использовании цветной принтер для повседневной печати...</description>
    <sales_notes>Необходима предоплата.</sales_notes>
    <manufacturer_warranty>true</manufacturer_warranty>
    <country_of_origin>Япония</country_of_origin>
  </offer>

Attributes of the <offer> element

The type attribute can have only one value — "vendor.model", — which means that the offer is custom.

Custom type: <offer id="1234567" type="vendor.model" available="true">
Simplified type: <offer id="0123456" available="true">

The type attribute determines which elements will be checked by the Yandex Direct robot when the feed is uploaded:

If you don't pass the type attribute, the offer will be simplified. The robot also checks for the <name> element. If it's missing, the offer is ignored and ads for the product aren't generated.

If you pass the type attribute, the offer will be custom. Remember to specify the <vendor> and <model> elements. If they are missing, an error occurs and the offer is ignored, meaning the product ads won't be launched.

Attribute	Description	Can be used for filter setup	Required element
`id`	Product ID. The IDs for each product must be unique. Check that the product `IDs` in E-commerce match the `offer ids` specified in the feed. This is necessary for offer retargeting impressions in YAN. Offer retargeting is only available for advertising products on a site. The `ID` value can consist of numbers, letters, or a combination of both. It may contain characters. Maximum length: 100 characters. Example 18295 1223abc a12b34fq	yes	yes
`type`	Product offering description type. The value must be `vendor.model.` If you pass the `type` attribute, this indicates you're using a custom description type. Yandex Direct checks for the `<vendor>` and `<model>` elements. If they are missing, the offer is ignored and product ads aren't generated.	no	for a custom description type
`available`	Availability of product: `true`: Product in stock; `false`: Product out of stock. By default, Yandex Direct assumes that all products present in the feed are in stock. If your feed includes out-of-stock items, you need to specify the `available` attribute for each offer. This allows filtering out offers when generating ads. The product availability information in the feed should match that on the landing page and checkout pages.	yes	required if the filter by product availability is used

Child elements of <offer> element

Element

Description

Can be used for filter setup

Required element

name

Product offering name

It's recommended that names of simplified offers include the manufacturer's name and code, as well as key offer features that the user may think important.

To create product names, you can use a universal formula: WHAT + WHO + MODEL and MODIFICATION, where:

“WHAT” is a category (type) or subcategory of the product;
“WHO” is the manufacturer, brand, or trademark;
“MODEL” is the product name, series, collection, or SKU.
“MODIFICATION” is the key product characteristics.

To ensure that Yandex Direct creates ads correctly, the product name should match the contents on the landing page.

The name shouldn't contain promotional text, such as “free delivery”. You also can't use all caps or special characters to attract user attention.

Example

<name>Smartphone Samsung Galaxy S22 Ultra 8/128 GB, blue</name>
<name>NOW — B-50 vitamin complex, 100 capsules</name>
<name>Long fitted knit black strapless dress</name>
<name>Loft Yellow Sofa with convertible mechanism by Monolith Factory</name>

yes

For a simplified type

typePrefix

Product type / category.

Specify the type of product based on how it's presented by the manufacturer. For example, “mobile phone”, “washing machine”, or “corner sofa”. Avoid using overly generic product type descriptions and ambiguous words.

Example

Adidas sneakers (VLNEO) V RACER NYLON

<typePrefix>Sneakers</typePrefix>
Smartphone Apple iPhone 15 Pro 1TB Natural Titanium

<typePrefix>Smartphone</typePrefix>

yes

for a free-form type

vendor

Manufacturer or brand (trademark). Providing the correct brand name is key for providing a good user experience and boosting sales.

Specify your own brand only if you sell own products or non-branded products of other manufacturers.

Example

Adidas sneakers (VLNEO) V RACER NYLON

<vendor>Adidas</vendor>
Smartphone Apple iPhone 15 Pro 1TB Natural Titanium

<vendor>Apple</vendor>

yes

for a free-form type

model

Model and key parameters (for example, name, model index, special modification features, and others).

Example

Adidas sneakers (VLNEO) V RACER NYLON

<model>(VLNEO) V RACER NYLON</model>
Smartphone Apple iPhone 15 Pro 1TB Natural Titanium

<model>iPhone 15 Pro 1TB Natural Titanium</model>

yes

for a free-form type

categoryId

Product category ID assigned by the advertiser (a positive integer of no more than 18 characters). The product offering can belong to only one category.

Example

<categoryId>12345</categoryId>

yes

The <offer> element can only contain one <categoryId> element.

url

A product page URL for advertising a site or a tracking link for advertising a mobile app. If you're advertising a mobile app, we recommend adding deferred deeplinks.

Maximum link length: 2048 characters. You can use links in Cyrillic. (We recommend converting links in Cyrillic characters using Punycode). The URL format follows the RFC 3986 standard.

Example

<url>https://www.example.ru/myagkaya-mebel/loft-ellou/</url>
<url>https://www.example.ru/myagkaya-mebel/loft-ellou/?product_id=351354&product_category_id=79&category_name=divan</url>

How to encode characters in a URL?

Symbol in text	Code for YML file
`"`	`"`
`&`	`&`
`>`	`>`
`<`	`<`
`'`	`'`

URLs must not contain spaces. Replace spaces with %20.

yes

picture

Image link.

We recommend adding five images to the feed. For example, images of the product shown from different angles or in different interiors. The product should occupy at least 2/3 of the entire image area.

In the Yandex Advertising Network, a single-product banner can be displayed as a carousel. If a format supports only one picture, the first image is selected, provided that its width and height are greater than or equal to the size of the ad unit. If the first image doesn't fit these requirements, the next one is considered for placement.

Product images should have a white background with a white frame of at least one pixel, without text and bright fonts. The image URL should include the http or https prefix.

Technical requirements:

Pixel size: 450 or more on each side.
Format: JPG, PNG, or GIF.
Maximum file size: 10 MB.

How do I change the image in the ad?

For the Yandex robot to update the product image in ads, change the link to it in the feed. For example:

Link to the current image: <picture>https://ikea.ru/images/1.png</picture>
Link to the new image: <picture>https://ikea.ru/images/1-new.png</picture>

For product ads and catalog page ads in unified performance campaigns.
For impressions in the product gallery.

description

Product offer description.

Provide a detailed description of important product characteristics that users base their choice on.

The description must not contain promotional text, such as “free delivery”, links to the site of the store, sales details, or information about competitors or other products, and their accessories.

Example

<description>A one-sided medium firmness mattress based on the EVS 500 independent springs block. Fillers: PU foam and latex coconut coir. Size: 90 x 195 cm, height: 17 cm. Maximum weight per sleeping space: 100 kg.</description>

yes

sales_notes

Order information:

minimum order price, minimum product quantity, required prepayment.
payment options, descriptions of promotions and sales.

Example

<sales_notes>Cash, MIR, Visa/Mastercard, non-cash payment</sales_notes>
<sales_notes>Prepayment required</sales_notes>
<sales_notes>Up to 60% off</sales_notes>

param

Specifying product characteristics and parameters.

The name attribute must include the parameter name.

When matching queries, Yandex Direct takes into account the following four types of param values: material, color, gender, and size. If you manage ad titles and texts manually, then param values don't affect ad generation. If you're using automatic generation, then several text variants are generated based on the offer elements, including param.

If the manufacturer uses custom color names — for example, mineral purple, — you should also provide the commonly accepted name for this color.

Example

Color:

<param name="Цвет">gray</param>

<param name="Color">gray</param>
Material:

<param name="Материал">aluminium</param>

<param name="Material">titanium</param>
Size (clothing):

<param name="Size" unit="INT">S</param>

<param name="Size" unit="RU">40</param>

When passing the size, be sure to specify the size chart: RU, EU, US, INT — international size designations (for clothes: XS, S, M, L, XL, XXL, 2XL, etc.; for bras: AA, A, B, C, etc.).
Dimensions:

<param name="Width" unit="cm">180</param>

<param name="Depth" unit="cm">70</param>

<param name="Height" unit="cm">90</param>

You can pass product dimensions using width, depth, height, and diameter. Be sure to specify the units of measurement: mm, cm, or m.
Gender:

<param name="Gender">female</param>

For example:

female, for women

male, for men

unisex, for men and women

price

The price at which this product is being offered.

Format: whole or decimal number.

The separator between the whole and decimal parts must be a dot.

The price must match the product price shown on the site and can't be zero.

This element is recommended for unified performance campaigns.

Example

<price>1234</price>
<price>1234.56</price>

yes

For impressions in the product gallery

oldprice

The old product price, which must be higher than the new price (price).

Format: whole or decimal number.

The separator between the whole and decimal parts must be a dot.

The price must not equal zero.

Your site should show both the old price and the current price.

You can display discounts in your ads if the feed includes the price and oldprice tags, and the difference between them is at least 5%.

Example

<price>1620</price>

<oldprice>1800</oldprice>
We don't show the discount amount because the difference between price and oldprice is less than 5%:

<price>1760</price>

<oldprice>1800</oldprice>

yes

currencyId

Currency code.

Supported values

RUR, RUB, USD, EUR, UAH, KZT, BYN, GBP, TRY, ALL, AFN, ARS, AWG, AUD, AZN, BBD, BZD, BMD, BOB, BAM, BWP, BGN, BRL, BND, KHR, CAD, KYD, CLP, CNY, COP, CRC, HRK, CUP, CZK, DKK, DOP, XCD, EGP, SVC, FKP, FJD, GHS, GIP, GTQ, GYD, HNL, HKD, HUF, ISK, INR, IDR, IRR, ILS, JMD, JPY, KPW, KRW, KGS, LAK, LBP, LRD, MKD, MYR, MUR, MXN, MNT, MAD, MZN, NAD, NPR, ANG, NZD, NIO, NGN, NOK, OMR, PKR, PAB, PYG, PEN, PHP, PLN, QAR, RON, SHP, SAR, RSD, SCR, SGD, SBD, SOS, ZAR, LKR, SEK, CHF, SRD, SYP, TWD, THB, TTD, AED, UYU, UZS, VEF, VND, YER, MDL, TJS, GEL, AMD, BHD, KWD.

if the price element is present

video

Link to product video.

Please provide an MP4 video up to 45 seconds long, that also meets other technical requirements.

Note

If the video is hosted on a platform that uses the HTTP protocol, it won't be served on resources using the HTTPS protocol.

The video should be filmed using a stable camera.

Content recommendations:

Talk about your product rather than your brand.
Avoid excessive text, vignettes, and blurring. Do not create an illusion that the video provides buttons or sound controls.
Demonstrate your product and the benefits of your offer in the first frame of your video.
Brand your videos: make sure the company's logo is visible.

Make individual videos for each product: this will make sure they match your ad title and text. You can only have one video per product.

Impressions only in YAN.

Example

<video>http://example.ru/catalog/video/19/6.MP4</video>

vendorCode

Product code (enter the vendor code).

Example

<vendorCode>A4068LM-12SG</vendorCode>

market_category

Product category to be used on Yandex Market.

yes

store

Product available in retail stores:

yes, 1, +, true — This product is available in stores.
no, 0, −, false — This product isn't available in stores.

yes

pickup

Customer pickup from delivery point:

yes, 1, +, true — This product is available for pickup.
no, 0, −, false — This product isn't available for pickup.

yes

delivery

Delivery by courier:

yes, 1, +, true — Courier delivery is available;
no, 0, −, false — Courier delivery isn't available.

manufacturer_warranty

Official warranty:

yes, 1, +, true — This product comes with an official warranty.
no, 0, −, false — This product doesn't come with an official warranty.

yes

country_of_origin

Country of origin.

Example

<country_of_origin>Russia</country_of_origin>
<country_of_origin>Belarus</country_of_origin>
<country_of_origin>Vietnam</country_of_origin>

age

Product age category.

A non-negative integer with or without the + prefix. If you use +, be sure to place it before the number.

We recommend specifying this element if the product is intended for certain age groups.

Example

<age>+6</age>
<age>18</age>

yes

adult

This product belongs to the “adult” category:

yes, 1, +, true — Yes.
no, 0, −, false — No.

yes

downloadable

Product download:

yes, 1, +, true — This product is available for download.
no, 0, −, false — This product isn't available for download.

collectionId

To serve ads in a combined format (ads for catalog pages and product ads), pass product links to the catalog. The value equals <collection id> in the <collections> element.

The value can consist of numbers, letters, or a combination of both.

One <offer> can contain several <collectionIds>.

yes

recommended if the feed has <collections>.

custom_label_0
custom_label_0
custom_label_0
custom_label_0
custom_label_4

Custom elements. Free-form description. Latin and Cyrillic characters and numbers. The maximum length of one element is 175 characters.

You can only use custom feed elements to create filters in unified performance campaigns. They don't affect the way creatives are generated. These filters are used for offer segmentation by specific parameters with no standard filters available. For instance, for e-commerce, you can set a filter by whether a product is part of a certain promotion.

yes

custom_score

Custom element. Value: 0 or any positive integer.

You can only use custom feed elements to create filters for unified performance campaigns. They don't affect the way creatives are generated. These filters are used for offer segmentation by specific parameters with no standard filters available. For instance, for e-commerce, you can set a filter by an offer's profit margin.

yes

Catalogs

In a YML feed, you can transmit information about product catalogs. In the tree structure, the <collections> element comes after the <offers> element.

Unified performance campaigns use information about catalogs only to advertise sites. Ads for mobile apps won't have any impressions.

Example of product sales feed:

  <?xml version="1.0" encoding="utf-8"?>
  <yml_catalog>
    <shop>

      <categories> ... </categories>
      <offers>
        <offer>...
          <collectionId>dukhi1</collectionId>
          <collectionId>kosmetika2</collectionId>
        </offer>
        <offer> ... </offer>
      </offers>

      <collections>
        <collection id="dukhi1">
          <url>httpss://example.ru/catalog/dukhi</url>
          <picture>httpss://example.ru/img/1.jpg</picture>
          <picture>httpss://example.ru/img/2.jpg</picture>
          <name>Мужские духи в интернет-магазине Example</name>
          <description>Мужские духи – подчеркните свой стиль </description>
        </collection>
        <collection id="kosmetika2">
          <url>httpss://example.ru/catalog/kosmetika</url>
          <picture>httpss://example.ru/img/3.jpg</picture>
          <picture>httpss://example.ru/img/4.jpg</picture>
          <name>Косметика для бритья в интернет магазине Example</name>
          <description>Косметика для бритья: приятный ежедневный уход</description>
        </collection>
      </collections>

    </shop>
  </yml_catalog>

Child elements of the <collections> element

Element

Description

Required element

collection id

Unique catalog ID. Maximum length: 60 characters. The value can be numeric, alphabetic, or alphanumeric.

The IDs for each catalog must be unique.

yes

url

URL of the catalog page.

Maximum link length: 2048 characters. You can use links in Cyrillic. (We recommend converting links in Cyrillic characters using Punycode). The URL format follows the RFC 3986 standard.

The URL must specify the http or https protocol.

How to encode characters in a URL?

Symbol in text	Code for YML file
`"`	`"`
`&`	`&`
`>`	`>`
`<`	`<`
`'`	`'`

URLs must not contain spaces. Replace spaces with %20.

yes

picture

Image link.

You can add multiple image links, each in its own picture element.

How do I change the image in the ad?

For the Yandex robot to update the catalog image in ads, change the link to it in the feed. For example:

Link to the current image — <picture>https://ikea.ru/images/1.png</picture>
Link to the new image — <picture>https://ikea.ru/images/1-new.png</picture>

for impressions in the Yandex Advertising Network and the product gallery

name

Catalog name.

yes

description

Catalog description.

1C-Bitrix users can quickly generate a feed with catalog pages by following the instructions.

If you work with the InSales platform and have set up automatic feed updates, catalog info will be automatically added to it, — with no additional actions required on your part. You can also create a feed with catalogs using a custom export to Yandex Market by following the instructions.

Questions?

Alert

Our customer service department can only help you with the campaigns created under the same username you use to contact us. You can check your username by opening ya.ru in another browser tab. Our team can access your data only when processing your request.

Message us on WhatsApp