Basic Format

The PersonaClick product feed is based on YML (Yandex Market Language), a more detailed description of which is available in the Yandex help section at the link: https://yandex.com/support/partnermarket/export/yml.html

Warning
All parameter names are case sensitive and should follow the spelling used in this documentation.

Supported Encodings

UTF-8
Windows-1251

Main tags

Tag	Required	Description
xml	required	Standard XML header. The header should start from the first line with the null character.
yml_catalog	required	Any XML document can contain only one root tag. The YML format uses the `yml_catalog` tag as the root tag.
shop	required	This tag contains a description of the store and its products.

"xml"

Available attributes:

Attribute	Required	Description
version	required	XML language version. Version "1.0" must be used.
encoding	required	XML encoding used.

Example:

Code Block

language	xml
theme	Midnight

<?xml version="1.0" encoding="UTF-8"?>

"yml_catalog"

Available attributes:

Attribute	Required	Description
date	required	The date attribute of the `yml_catalog` tag must match the date and time the YML file was generated on the store side. The date should be in the `YYYY-MM-DD hh:mm` format.

Example:

Code Block

language	xml
theme	Midnight

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    ...
</yml_catalog>

"shop"

shop's child tags:

Tag	Required	Description
name	required	The short name of the store.
company	required	Full name of the company that owns the store.
url	required	URL of store's home page.
currencies	required	List of store's exchange rates.
categories	required	List of store's categories.
locations	optional	List of store's locations.
offers	required	List of store's products.

"name"

Example:

Code Block

language	xml
theme	Midnight

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        <name>My store</name>
        ...
    </shop>
</yml_catalog>

"company"

Example:

Code Block

language	xml
theme	Midnight

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        ...
        <company>My company</company>
        ...
    </shop>
</yml_catalog>

"url"

Example:

Code Block

language	xml
theme	Midnight

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        ...
        <url>https://my-store.com</url>
        ...
    </shop>
</yml_catalog>

"currencies"

The currencies tag sets a list of the store's exchange rates. Each currency is described in a separate currency tag.

The currency tag attributes are:

Attribute	Required	Description
id	required	The `id` attribute of the `currency` tag specifies the code of a particular currency that can be used in the YML file.
rate	required	The `rate` attribute specifies the exchange rate between the selected currency and the main currency taken as a unit (currency for which `rate="1"`). All numbers in YML use the dot as the decimal separator, regardless of regional settings (never use the comma).

Example:

Code Block

language	xml
theme	Midnight

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        ...
        <currencies>
            <currency id="TRY" rate="1"/>
            <currency id="USD" rate="6.45"/>
            <currency id="EUR" rate="7.12"/>
            ...
        </currencies>
        ...
    </shop>
</yml_catalog>

"categories"

The parent tag categories describes the list of store categories in YML format. Each category is described in a separate category tag.

The category tag attributes are:

Attribute	Required	Description
id	required	The category identifier.
parentId	optional	The parent category identifier. If used, the parent category must be in the category list.
url	optional	Category page URL.
alias	optional	Wordy category identifier

Example:

Code Block

language	xml
theme	Midnight

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        ...
        <categories>
            <category id="2" url="http://my-store.com/categories/discount/">Sale</category>
            <category id="8" url="http://my-store.com/categories/men/">Men</category>
            <category id="13" parentId="8" url="http://my-store.com/categories/men/shoes/">Shoes</category>
            <category id="97" parentId="13" alias="men/shoes/leather" url="http://my-store.com/categories/men/shoes/leather">Leather Shoes</category>
            ...
        </categories>
        ...
    </shop>
</yml_catalog>

"locations"

The locations tag sets a list of the store's locataions. Each location is described in a separate location tag.

The location tag attributes are:

Attribute	Required	Description
id	required	The location identifier.
parentId	optional	The parent location identifier.
type	optional	The location type. Available values are: city, store.
name	optional	The location name.
group	optional	Grouping of locations by any custom property. For example: "cash only", "wholesale", etc.

Example:

Code Block

language	xml
theme	Midnight

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
        ...
        <locations>
            <location id="1" type="city" name="Los Angeles" />
            <location id="2" type="city" name="Istanbul" />
            <location id="145" parentId="1" type="store" name="Central District store" />
            ...
        </locations>
        ...
    </shop>
</yml_catalog>

"offers"

The offers tag sets a list of the store's products. Each offer is described in a separate offer tag.

Warning
This tag should be last in the tag list of the `shop` tag.

The offer tag attributes are:

Attribute

Required

Description

id

required

The product identifier.

group_id

optional

Used to combine several variants of the same product into a group. The system will automatically use the most relevant product variant in the tools.

Note
If the product variants don't have this property, the system will consider each product variant as a separate product.

available

required

The product availability. Available values are: true, false.

leftovers

optional

Rough number of the products left in stock. Available values are:

one - one product
few - 2-10 products
lot - over 10 products

offer's child tags:

Tag

Required

Description

name

required

Full offer name that includes: product type, manufacturer and product name. See the following tags for separate use: typePrefix, vendor, model.

picture

required

Product image URL.

price

required

Base product price.

url

required

URL of the product page on the store's website.

deeplink_android

optional

Deep link to a product for an Android app.

deeplink_ios

optional

Deep link to a product for an iOS app.

categoryId

required

Product category ID assigned by the store. It's possible to use several of these tags.

locations

optional

Tag describing the properties of a product in different locations: availability, price. See table and example below.

Note
If the tag isn't used, the product is considered available in all known locations.

accessories

optional

Tag describing the list of accessories for the current product. See example below.

customerRecommendations

optional

Warning
This has a similar meaning to the "accessories" property. Support for this property will be discontinued on 2024-01-01.

oldprice

optional

The old price of the product should be higher than the current one.

price_margin

optional

Relative marginality (priority) of the product.

Warning
It only can be a value from 0 to 100 (in percent). Using values greater than 100 leads to unpredictable results of calculation formulas.

barcode

optional

Product manufacturer's barcode in one of the following formats: EAN-13, EAN-8, UPC-A, or UPC-E.

typePrefix

optional

Type/category of product (for example: "mobile phone", "washing machine", "corner sofa").

vendor

optional

Manufacturer/brand.

vendorCode

optional

Manufacturer product code.

model

optional

Model and product name.

seasonality

optional

Product seasonality. The sequence number of the month (from 1 to 12) is used as the value. These tags may be several.

is_new

optional

It can take only one value - "1", which means that the product is new.

rating

optional

Product rating. Integer value from 1 to 5.

description

optional

Product description.

stock_quantity

optional

The available quantity of products. Integer value from 1 and more.

"locations"

The locations tag contains a list of locations, includes the current product availability and price in locations. Each location is described by a separate location tag.

The location tag attributes are:

Attribute	Required	Description
id	required	Locations identifier. Must match one of the locations (identifier) described in `shop`/`locations` list. More information about the location, see the subsection above and in the example below.

Note
Please note, the product will be considered available for purchase only in the locations listed in the `offer` tag, in all other known but not listed locations the product will be considered unavailable for purchase.

Child tags:

Tag	Required	Description
price	optional	Product price in location. The product will use the base price if this tag is missing.
oldprice	optional	Product old price in location. The product will use the base old price if that exists and this tag is missing.

"tags"

The tags tag contains a list of tags that relate to the product. Each value is described by a separate tag tag.

Tag	Required	Description
tag	optional	Tag value.

"param"

One param tag describes one characteristic. The offer tag can contain any number of param tags.

Code Block

language	xml
theme	Midnight

<param name="ANY_NAME" unit="MEASUREMENT_UNIT">VALUE</param>

Item	Property type	Required	Description
name	attribute	required	In this attribute, specify the parameter name.
unit	attribute	required for numeric values	In this attribute, specify the measurement units.

Full Basic Example

Code Block

language	xml
theme	Midnight

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2021-04-26 17:19">
    <shop>
		<name>My store</name>
		<company>My company</company>
		<url>https://my-store.com</url>
		<!-- list of store currencies and exchange rates -->
        <currencies>
            <currency id="TRY" rate="1"/>
            <currency id="USD" rate="6.78"/>
            <currency id="EUR" rate="7.56"/>
        </currencies>
		<!-- list of all store categories, their hierarchies and links -->
        <categories>
            <category id="2" url="http://my-store.com/categories/apple/">Apple</category>
            <category id="13" parentId="2" alias="apple/phones" url="http://my-store.com/categories/apple/phones/>Phones</category>
        </categories>
		<!-- list of all store locations -->
        <locations>
            <location id="1" type="city" name="Los Angeles" />
            <location id="2" type="city" name="Istanbul" />
			<location id="3" type="city" name="London" />
        </locations>
		<offers>
			<offer id="395532" group_id="3955" available="true" leftovers="few">
				<url>http://my-store.com/items/395532</url>
				<deeplink_android>app_android://395532</deeplink_android>
				<deeplink_ios>app_ios://395532</deeplink_ios>
				<price>50000</price>
				<oldprice>55000</oldprice>
				<price_margin>67</price_margin>
				<!-- list of categories hierarchies in which this product is present -->
				<categoryId>2</categoryId>
				<categoryId>13</categoryId>
				<!-- Seasonality list. The months to recommend the product are January, March, April, June. -->
				<seasonality>1</seasonality>
				<seasonality>3</seasonality>
				<seasonality>4</seasonality>
				<seasonality>6</seasonality>
				<!-- product locations list and the price in the location -->
				<locations>
					<location id="1">
						<price>70000</price>
						<oldprice>75000</oldprice>
					</location>
					<!-- id="2" location is not specified, it means this product isn't available in this location -->
					<!-- price for id="3" location is not set, it means the price is equal to the base price -->
					<location id="3"></location>
				</location>
				<!-- list of product IDs that are accessories for the current product -->
				<accessories>
					<accessory id="5574" />
					<accessory id="131" />
					<accessory id="99444" />
					<accessory id="334411" />
				</accessories>
                <tags>
                    <tag>phone</tag>
                    <tag>smartphone</tag>
                </tags>
				<customerRecommendations>18,21,146,100500</customerRecommendations>
				<barcode>123456</barcode>
				<picture>https://my-store.com/items/395532.jpg</picture>
				<name>Apple Iphone 7 128 gb</name>
				<typePrefix>Smartphone</typePrefix>
				<vendor>Apple</vendor>
				<vendorCode>APPL</vendorCode>
				<model>iPhone 7 128Gb</model>
				<is_new>1</is_new>
				<rating>5</rating>
                <date>2023-04-13</date>
				<param name="display" unit="inch">5.5</param>
				<param name="material">aluminum</param>
				<param name="Wi-Fi">true</param>
				<description><![CDATA[The moment you connect with iPhone 7, you will know you've never felt anything like it. With a single press, 3D Touch lets you do more than ever before. Live Photos bring your memories to life in a powerfully vivid way. And that's just the beginning. Take a deeper look at iPhone 7, and you'll find innovation on every level.]]></description>
			</offer>
			<offer id="395533" group_id="3955" available="false">
				...
			</offer>
			...
		</offers>
    </shop>
</yml_catalog>

Additional Niches Properties

Additional niches properties of products allow studying user preferences and calculating recommendations more accurately. If there are products from the niches listed below in the product catalog, you should add this extended data to the product feed.

Niche	Description
Apparel & Accessories	Allows filling the product feed with niche features of apparel and accessories.
Auto Products	Allows filling the product feed with vehicle niche features.
Baby & Children	Allows filling the product feed with niche features of products for children and babies.
Construction & Repair	Allows filling the product feed with niche features of products for construction and repair.
Cosmetics & Perfumes	Allows filling the product feed with niche features of cosmetics and perfumes.
Fast-Moving Consumer Goods (FMCG)	Allows filling the product feed with niche features of Fast-Moving Consumer Goods (FMCG).
Jewelry	Allows filling the product feed with jewelry niche features.
Pet Products	Allows filling the product feed with niche features of pet products.
Real Estate	Allows filling the product feed with niche features of real estate.

Creating the XML file

If you create the XML file on request, you should make sure that the time to creating the file and download it by the system doesn't take more than 10 minutes. Otherwise, you should create a static XML file at specified intervals and give it to the system when the product feed is requested. Additionally, you can use GNU GZIP file compression. If the time limit is still not enough, you should use HTTP API to import the product catalog.

Multiple Requests

The system makes multiple simultaneous requests to download product feed and product images. Check the IP list and make sure they are all whitelisted on your side.

Column

Page Navigation

Table of Contents

maxLevel	4
indent	3px
style	none

Related Pages

Filter by label (Content by label)

showLabels	false
showSpace	false
sort	title
cql	label = "products"

Versions Compared

Old Version 46

New Version 47

Key

Basic Format

Supported Encodings

Main tags

"xml"

"yml_catalog"

"shop"

"name"

"company"

"url"

"currencies"

"categories"

"locations"

"offers"

"locations"

"tags"

"param"

Full Basic Example

Additional Niches Properties

Creating the XML file

Multiple Requests

Page Comparison

Versions Compared

Old Version 46

New Version 47

Key

Basic Format

Supported Encodings

Main tags

"xml"

"yml_catalog"

"shop"

"name"

"company"

"url"

"currencies"

"categories"

"locations"

"offers"

"locations"

"tags"

"param"

Full Basic Example

Additional Niches Properties

Creating the XML file

Multiple Requests