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/ymlexport/about-yml.html

Supported Encodings

UTF-8
Windows-1251

Main elements

Element

Case Sensitivity

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

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 elementtag. The YML format uses the `yml_catalog` element tag as the root elementtag.
shop	required	This element 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	FadeToGreyMidnight

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

"yml_catalog"

Available attributes:

Attribute	Required	Description
date	required	The date attribute of the `yml_catalog` element 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	FadeToGreyMidnight

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

"shop"

shop's child elementstags:

ElementTag	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	FadeToGreyMidnight

<?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	FadeToGreyMidnight

<?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	FadeToGreyMidnight

<?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 currencieselement tag sets a list of the store's exchange rates. Each currency is described in a separate currency element tag.

The currencyelement tag attributes are:

Attribute	Required	Description
id	required	The `id` attribute of the `currency`element 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	FadeToGreyMidnight

<?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 element tag categories describes the list of store categories in YML format. Each category is described in a separate category element tag.

The categoryelement 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	FadeToGreyMidnight

<?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 element tag sets a list of the store's locataions. Each location is described in a separate location element tag.

The location element 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	FadeToGreyMidnight

<?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 element tag sets a list of the store's products. Each offer is described in a separate offer element tag.

Note

Please note, the offer element cannot contain a product variant, only the product itself. If in your store all variants of product are on the same page and there is no common product identifier then you need to use one of the variant as the main one - its identifier, price and other data. Usually, the low cost variant is chosen as the main one and the availability flag in this case should fit into the following logic: if at least one variant is in stock then the product should be marked as available.

The offer element attributes are:

AttributeRequiredDescriptionidrequiredThe product identifier.

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.

Note
If "false" is used, only an existing product will have its status changed, but if a product with that status is imported for the first time, it won't be imported.

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 elementstags:

margin

ElementTag

Required

Description

name

required

Full offer name that includes: product type, manufacturer and product name. See the following elements 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.

categoryId

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 elementstags.

locations

optional

Element

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

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

customerRecommendations

optional

Element describing the list of custom recommended products for the current product. See example below.

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

discount_

percent

optional

Relative marginality (priority) of the product (from 0 to 100).

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 elements 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 0 to 5, where 0 is a product without a rating, 1-5 is a rating.

description

optional

Product description.

stock_quantity

optional

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

"locations"

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

The location element attributes are:

AttributeRequiredDescriptionidrequiredLocations 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` element, in all other known but not listed locations the product will be considered unavailable for purchase.

Child elements:

ElementRequiredDescriptionpriceoptionalProduct price in location. The product will use the base price if this element is missing.oldpriceoptionalProduct old price in location. The product will use the base old price if that exists and this element is missing.

"tags"

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

ElementRequiredDescriptiontagoptionalTag value.

"param"

One param element describes one characteristic. The offer element can contain any number of param elements.

Code Block

language	xml
title	Structure

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

ItemProperty typeRequiredDescriptionnameattributerequiredIn this attribute, specify the parameter name.unitattributerequired for numeric valuesIn this attribute, specify the measurement units.

Full Basic Example

Code Block

language	xml
theme	FadeToGrey

<?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>

User-defined discount value.

Tip
Usually, the "price" and "old_price" values are used to calculate the discount value. The "discount_percent" property allows to set the discount value in advance.

installment

optional

The payment cost if purchasing the product in installments.

promocode

optional

The promo code is for a specific product.

price_with_promocode

optional

The product price when using the promo code specified for the product.

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.

gift

optional

Specifies whether the product is a gift.

description

optional

Product description.

Note
Please contact your account manager to activate this property.

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>
				<price>50000</price>
				<oldprice>55000</oldprice><deeplink_android>app_android://395532</deeplink_android>
				<deeplink_ios>app_ios://395532</deeplink_ios>
				<price_margin>67</price_margin><price>50000</price>
				<!-- list of categories hierarchies in which this product is present -->
				<categoryId>2</categoryId>
				<categoryId>13</categoryId>
				<!-- Seasonality list. Priority months for this product: January, March, April, June. -->
				<seasonality>1</seasonality>
				<seasonality>3</seasonality>
				<seasonality>4</seasonality>
				<seasonality>6</seasonality><oldprice>55000</oldprice>
                <discount_percent>9</discount_percent>
                <installment>4200</installment>
				<price_margin>67</price_margin>
				<!-- product locations list andof thecategories pricehierarchies in thewhich this locationproduct -->
				<locations>
					<location id="1"is present -->
						<price>70000<<categoryId>2</price>categoryId>
					<<categoryId>13</location>categoryId>
					<!-- id="2" location is not specified, it means this product isn't available in this locationSeasonality list. The months to recommend the product are January, March, April, June. -->
				<seasonality>1</seasonality>
				<seasonality>3</seasonality>
				<seasonality>4</seasonality>
				<seasonality>6</seasonality>
				<!-- priceproduct for id="3" location is not set, it means locations list and the price isin equal to the baselocation price -->
				<locations>
					<location id="3"></location>1">
						<price>70000</price>
						<oldprice>75000</oldprice>
					</location>
					<!-- list of product IDs that are accessories for the current product id="2" location is not specified, it means this product isn't available in this location -->
				<accessories>
					<accessory	<!-- price for id="5574" />
					<accessory id="131" /3" location is not set, it means the price is equal to the base price -->
					<accessory<location id="994443" ></>location>
					<accessory id="334411" /></location>
				</accessories>!-- list of product IDs that are accessories for the current product -->
				<accessories>
					<accessory id="5574"  <tags>
        />
					<accessory id="131" />
					<accessory id="99444" />
					<accessory id="334411" />
				</accessories>
           <tag>phone</tag>     <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>
				<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" available="false">
				...
			</offer>
			...
		</offers>
    </shop>
</yml_catalog>

Additional Niches Data

Apparel & Accessories "<fashion>"

A distinctive feature of a product from Apparel & Accessories category is presence of the <fashion> subsection inside the <offer> section. Add the following parameters to each product to your XML file.

Gender

Optional parameter <gender>. Placed inside the <offer> section, within the <fashion> subsection.

Consider the following table of possible attributes:

ValueDescriptionmMalefFemale

Consider the following example of use:

Code Block

language	xml
title	XML example

 ...
<offer ...>
    ...
	<fashion>
	    <gender>f</gender>
	</fashion>
</offer>
...

Info
No need to specify the gender this particular product is targeted at, if you do not have this data (gender). In this case, this particular product will simply be marked as 'unisex' and will have a lower displaying priority in relation to other products with the specified gender parameter.

Clothing Type

Mandatory parameter <type>. Placed inside the <offer> section, within the <fashion> subsection.

Consider the following table of possible attributes:

ValueDescriptionshoeShoesshirtShirts, blouses and dressestshirtT-shirtunderwearUnderweartrouserPants, jeans, shorts, skirts and swimsuitsjacketJackets, coats, fur coatsblazerBlazers, vests,pullovers and cardiganssockSocksbeltBeltshatHatsgloveGloves

Info
No need to specify the type of the particular product if you do not have the size parameter.

Consider the following example of use:

Code Block

language	xml
title	XML example

...
<offer ...>
	...
	<fashion>
		<gender>f</gender>
		<type>shoe</type>
	</fashion>
</offer>
...

Clothing Size

Mandatory parameter <sizes>. Placed inside the <offer> section, within the <fashion> subsection.

Taking into account variety of world sizing systems,every clothing size should have the respective prefix.

Consider the following table of possible prefixes:

Sizing systemDescriptionExamplePrefix is not needed or prefix is 'r'Russian sizing systemr44, 44'e'European sizing systeme38Prefix is not needed, if only the letters used, otherwise - prefix 'u'U.S. / international sizing systemXS, u30'b'British sizing systemb6'h'Height (for baby and children apparel)h89-95Prefix is not neededUnisize (fits all sizes)null

Info
Single product can have more than one size, hence all the available sizes should be passed in the form of a list - each size wrapped in the tag `<size>`.

Consider the following example of use:

Code Block

language	xml
title	XML example

 ...
<offer ...>
	...
	<fashion>
		<gender>f</gender>
		<type>shoe</type>
		<sizes>
			<size>e40</size>
			<size>e42</size>
			<size>e44</size>
			<size>e48</size>
		</sizes>
	</fashion>
</offer>
...

Color

Optional parameter <color>. Placed inside the <offer> section.

Info
One product can have several colors. The "picture" attribute may be missing, in which case the main image of the product is used.

Consider the following example of use:

Code Block

language	xml
title	XML example

 ...
<offer ...>
	...
	<fashion>
		<gender>f</gender>
		<type>shoe</type>
		<sizes>
			<size>e40</size>
			<size>e42</size>
			<size>e44</size>
			<size>e48</size>
		</sizes>
        <color>red></color>
        <color picture="https://mystore.com/product/100500/pictures/yellow.jpg">yellow</color>
	</fashion>
</offer>
...

Features

Optional parameter <feature>. Placed inside the <offer> section, within the <fashion> subsection.

Consider the following table of possible attributes:

ValueDescriptionpregnantMaternity clothingchildChildren's clothingadultClothing for adults (default value)

Consider the following example of use:

Code Block

language	xml
title	XML example

 ...
<offer ...>
    ...
	<fashion>
	    <gender>f</gender>
	    <type>jacket</type>
		<feature>pregnant</feature>
	</fashion>
</offer>
...

Generate a Static File

If your XML-file weighs more than 5 megabytes and its generation by the script takes more than 20 seconds, set a scheduled Cron task to generate your XML-file (read "don't give us a direct link to the script that generates the file").

It will give you the following advantages:

Reduction of your server workload (without a direct link to the script it would be not possible for somebody to easily organize a DDOS-attack with multiple requests to the script)
Instant download of your XML-file: PersonaClick will be able to instantly download the XML-file and have the most recent catalog updates from you. That ensures your success - the products will always hold highest marketing potential.

Example of scheduled XML-file generation for Cron:

Code Block
0 /2 * * php /home/myuser/site/docs/xml.php > /home/myuser/site/docs/personaclick.xml

Info

title	NOTE

In order to speed up the download of your XML-file,, you can compress it using GNU GZIP. Personaclick fully supports .gzip format and auto-exacts files for further processing.

Warning

title	MULTIPLE REQUESTS

To load all product images, PersonaClick may send your server multiple requests. If you notice your server blocks multiple requests from IP 94.130.90.232, 88.99.217.82 and 88.99.209.134 (PersonaClick Technologies), please add this IP address to your white list. Otherwise, PersonaClick will not be able to access product images, and products without images may be excluded from recommendations.
All API requests also have the "PERSONACLICK Fetcher 1.0" User-Agent.

Table of Contentsclasspersonaclick-fixed-position

                <gift>false</gift>
                <promocode>OLDSCHOLL</promocode>
                <price_with_promocode>45000</price_with_promocode>
                <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 12

New Version Current

Key

Basic Format

Main elements

Case Sensitivity

Main tags

"xml"

"yml_catalog"

"shop"

"name"

"company"

"url"

"currencies"

"categories"

"locations"

"offers"

"locations"

"tags"

"param"

Full Basic Example

"locations"

"tags"

"param"

Full Basic Example

Additional Niches Data

Apparel & Accessories "<fashion>"

Gender

Clothing Type

Clothing Size

Color

Features

Generate a Static File

Additional Niches Properties

Creating the XML file

Multiple Requests

Page Comparison

Versions Compared

Old Version 12

New Version Current

Key

Basic Format

Main elements

Case Sensitivity

Main tags

"xml"

"yml_catalog"

"shop"

"name"

"company"

"url"

"currencies"

"categories"

"locations"

"offers"

"locations"

"tags"

"param"

Full Basic Example

"locations"

"tags"

"param"

Full Basic Example

Additional Niches Data

Apparel & Accessories "<fashion>"

Gender

Clothing Type

Clothing Size

Color

Features

Generate a Static File

Additional Niches Properties

Creating the XML file

Multiple Requests