YML feed requirements - Yandex Direct. Help

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.

YML is a format developed by Yandex 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 offers is contained in the <offers> element. Each product offer is described in a separate <offer>element. Add the <currencies> and <categories> elements to the <shop> element before the list of product offers. To learn more about elements comprising <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 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

This is the basic, simpler type of description.

Example:

<offer id="0123456" available="true">
  <url>http://www.reliableappliances.biz/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 Antivirus</name>
  <vendor>Eset</vendor>
  <vendorCode>NOD32-ENA-NS(BOX)-2-1</vendorCode>
  <description>ESET NOD32 Platinum Edition Antivirus: 2-year license for NOD32-ENA-NS(BOX)-2-1</description>
  <video>http://89.123.45.678/catalog/video/19/6.MP4</video>
  <sales_notes>Payment: cash, wire transfer, bank card, loan</sales_notes>
  <manufacturer_warranty>true</manufacturer_warranty>
  <country_of_origin>Russia</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.reliableappliances.biz/catalog/element/index.php?from=ya_market&utm_source=ya_market&utm_medium=cpc&</url>
  <price>889.00</price>
  <oldprice>17,000.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>Printer</typePrefix>
  <vendor>НP</vendor>
  <model>Deskjet D2663</model>
  <description>Portfolio of printers for people who need a reliable, easy-to-use color printer for everyday printing...</description>
  <sales_notes>Prepayment is required.</sales_notes>
  <manufacturer_warranty>true</manufacturer_warranty>
  <country_of_origin>Japan</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. The `ID` value can be numeric, alphabetic, or alphanumeric. It may contain characters. The maximum length is 100 characters. Example 18295 1223abc a12b34fq	yes	yes
`type`	Product offering description type. The value should be `vendor.model`. If you pass the `type` attribute, this indicates you are 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 is in stock `false`: Product is 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


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. The `ID` value can be numeric, alphabetic, or alphanumeric. It may contain characters. The maximum length is 100 characters. Example 18295 1223abc a12b34fq	yes	yes
`type`	Product offering description type. The value should be `vendor.model`. If you pass the `type` attribute, this indicates you are 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 is in stock `false`: Product is 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 the <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.

You can name your product using 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 custom 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 custom 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 contain only one <categoryId> element

url

URL of the product page.

The maximum link length is 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.

Example

<url>https://www.example.ru/myagkaya-mebel/loft-ellou/</url>
<url>https://www.example.ru/soft-furniture/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 smart banners.
For product ads in unified performance campaigns with impressions in YAN.
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: 90x195 cm, height: 17 cm. Maximum weight per sleeping spot: 100 kg.</description>

yes

sales_notes

Order information:

minimum order price, minimum product consignment, 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="Цвет">серый</param>

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

<param name="Материал">алюминий</param>

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

<param name="Размер" unit="RU">40</param>

<param name="Size" unit="INT">S</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.

Recommended element for dynamic ads, smart banners, and 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.

Make sure to provide both old and current prices on your site.

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.

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.

yes

store

Product available in retail stores:

yes, 1, +, true — Available.
no, 0, −, false — Not available.

yes

pickup

Customer pickup from delivery point:

yes, 1, +, true — Available.
no, 0, −, false — Not available.

yes

delivery

Delivery by courier:

yes, 1, +, true — Available.
no, 0, −, false — Not available.

manufacturer_warranty

Official warranty:

yes, 1, +, true — Available.
no, 0, −, false — Not available.

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 "+", make 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

The product is in the “adult” category:

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

yes

downloadable

Product download:

yes, 1, +, true — Available.
no, 0, −, false — Not available.

collectionId

To serve ads in a combined format (ads for catalog pages and product ads), pass product links to the