Overview

This document contains the item feed specification for onboarding.

The item feed includes a product catalog. The item ID should correspond to the same ID available on the website (as well as other entities like category IDs).

Note

In general, item_id from item feed must be interconnected with data coming from the Data Collector (collector is sending events with item_id that is parsed directly from the website).

Item feed should be updated at regular intervals, ideally once per 15 minutes to minimize delay in marking products as unavailable/out-of-stock or having an obsolete price tag.

Alternatively, when it is not possible to update the item feed regularly (due to the item feed total file size or other restrictions), a separate feed - availability feed can be provided containing only data for item availability or price updates.

Categories and brands

You can provide category and brand data in two ways:

Provide the full category and brand data directly in the item feed. This is usually fine for smaller catalogues, for example thousands of products and feed sizes in the low tens of MBs.
Provide only category IDs and brand IDs in the item feed, and keep the full metadata in the separate Category Feed and Brand Feed. Consider this when the catalogue is large, for example 50k items or more and feed sizes above 30 MB.

Do not duplicate the same category or brand metadata in both places unless you have a specific reason to do so. Repeating names, paths, URLs, and icons on every item makes the item feed larger and more expensive to download and synchronize.

For categories, Perselio usually integrates with the taxonomy that already exists in your source system and on the website. In most cases, keep that taxonomy as-is rather than introducing a mapping layer.

You can also simplify or remap categories before sending them to Perselio if there is a clear reason to do so. This can make the integration model simpler in some cases, but it also creates another layer that can drift away from the website and become harder to debug.

Full Example

<?xml version="1.0" encoding="UTF-8" ?>
<perselio_item_feed>
    <item>
        <id>ps5-ea-sports-fc-26-standard</id>
        <grouping_id>ea-sports-fc-26</grouping_id>
        <name>EA SPORTS FC 26 Standard Edition for PlayStation 5</name>
        <description><![CDATA[Official PlayStation 5 edition with online and local multiplayer modes.]]></description>
        <available>true</available>
        <in_stock_count>24</in_stock_count>
        <in_stock_text>In stock</in_stock_text>
        <availability_text>Delivery tomorrow</availability_text>
        <shipped_in_days>1</shipped_in_days>
        <brand>PlayStation</brand>
        <brand_id>playstation</brand_id>
        <brand_url>https://www.eshop.com/brands/playstation</brand_url>
        <brand_image_url>https://cdn.eshop.com/brands/playstation/logo-200x200.png</brand_image_url>
        <url>https://www.eshop.com/gaming/playstation-5-games/ea-sports-fc-26-standard-edition</url>
        <image_url>https://cdn.eshop.com/products/ea-sports-fc-26-standard-ps5/main-800x800.jpg</image_url>
        <image_urls_alt>
            <image_url>https://cdn.eshop.com/products/ea-sports-fc-26-standard-ps5/front-800x800.jpg</image_url>
            <image_url>https://cdn.eshop.com/products/ea-sports-fc-26-standard-ps5/back-800x800.jpg</image_url>
            <image_url>https://cdn.eshop.com/products/ea-sports-fc-26-standard-ps5/gallery-1-800x800.jpg</image_url>
        </image_urls_alt>
        <add_to_cart_id>sku-1004589</add_to_cart_id>
        <rating>0.92</rating>
        <rating_count>184</rating_count>
        <age_rating>3</age_rating>
        <price>59.99</price>
        <price_old>69.99</price_old>
        <labels>
            <label>
                <id>new-release</id>
                <text>New release</text>
                <background_color_hex>#1d4ed8</background_color_hex>
                <background_image_url>https://cdn.eshop.com/labels/new-release-bg.png</background_image_url>
                <font_color_hex>#ffffff</font_color_hex>
                <order>1</order>
            </label>
            <label>
                <id>best-seller</id>
                <text>Best seller</text>
                <background_color_hex>#111827</background_color_hex>
                <background_image_url>https://cdn.eshop.com/labels/best-seller-bg.png</background_image_url>
                <font_color_hex>#f9fafb</font_color_hex>
                <order>2</order>
            </label>
        </labels>
        <coupons>
            <coupon>
                <id>weekend-deal</id>
                <text>Weekend deal</text>
                <code>PLAY10</code>
                <discount_percentage>10</discount_percentage>
                <discount_price>53.99</discount_price>
                <background_color_hex>#dc2626</background_color_hex>
                <background_image_url>https://cdn.eshop.com/coupons/weekend-deal-bg.png</background_image_url>
                <font_color_hex>#ffffff</font_color_hex>
                <order>1</order>
            </coupon>
        </coupons>
        <categories>
            <category>
                <id>ps5-games</id>
                <name>PlayStation 5 Games</name>
                <path>Gaming | PlayStation 5 Games</path>
                <url>https://www.eshop.com/gaming/playstation-5-games</url>
                <image_url>https://cdn.eshop.com/categories/ps5-games/icon-200x200.png</image_url>
            </category>
        </categories>
        <parameters>
            <parameter>
                <id>platform</id>
                <text>Platform</text>
                <value>PlayStation 5</value>
            </parameter>
            <parameter>
                <id>edition</id>
                <text>Edition</text>
                <value>Standard Edition</value>
            </parameter>
        </parameters>
        <reviews>
            <review>Fast delivery and everything worked right after installation.</review>
            <review>Great football game with improved career mode.</review>
        </reviews>
        <files>
            <file>
                <id>manual</id>
                <url>https://ehop.com/PRODUCT-DATA/12010100_31-B964.pdf</url>
            </file>
        </files>
    </item>
</perselio_item_feed>

Individual Tags Documentation

All tags are mandatory except those explicitly marked as optional.

`<id>: string`

The main identifier of the item (product). It must be unique within the feed. It must be the same ID that is used on the client's website so that events collected on the website can be mapped to items in the item feed.

`<grouping_id>: string (optional)`

An optional ID for grouping similar items into item groups (usually used to define item variants). In this context, a variant typically refers to the same item with different parameters, for example:

variants of a mobile phone model that differ in color, RAM size, etc.
clothing/shoes, where each variant has a unique size/color pair

If the data model includes the concept of a master item, the feed may contain both the master item and all its variants. In such cases, the grouping_id for the master item will be set the same as its id.

The following example illustrates a master item and 2 of its variants for a T-shirt (note: unnecessary tags omitted for clarity):

for the master item, the grouping_id == id
for the variants, the grouping_id == id of the master item
price in the master item will be used in the widget as the main one in case the variants have different prices and the widgets display master items and not variants

<?xml version="1.0" encoding="UTF-8" ?>
<!-- note: most tags omitted for clarity -->
<perselio_item_feed>
    <!-- master item -->
    <item>
        <id>summer-t-shirt</id>
        <grouping_id>summer-t-shirt</grouping_id>
        <price>9.99</price>
    </item>
    <!-- variant 1 red / xl-->
    <item>
        <id>summer-t-shirt-red-xl</id>
        <grouping_id>summer-t-shirt</grouping_id>
        <price>12.99</price>
        <parameters>
            <parameter>
                <id>color</id>
                <text>Barva</text>
                <value>červená</value>
            </parameter>
            <parameter>
                <id>size</id>
                <text>Velikost</text>
                <value>XL</value>
            </parameter>
        </parameters>
    </item>
    <!-- variant 2 blue / xs -->
    <item>
        <id>summer-t-shirt-blue-xs</id>
        <grouping_id>summer-t-shirt</grouping_id>
        <price>13.99</price>
        <parameters>
            <parameter>
                <id>color</id>
                <text>Barva</text>
                <value>modrá</value>
            </parameter>
            <parameter>
                <id>size</id>
                <text>Velikost</text>
                <value>XS</value>
            </parameter>
        </parameters>
    </item>
</perselio_item_feed>

`<name> : string`

Item (product) name

`<description> : string`

Item (product) description as it appears on the website. If it contains HTML, it needs to be wrapped in CDATA.

`<available>: boolean`

The value true indicates that the item is available, either in-store or in stock from which it can be immediately dispatched. false indicates that the item is temporarily or permanently unavailable.

`in_stock_count: integer (optional)`

Number of items in stock.

`in_stock_text: string (optional)`

Text that briefly describes how many pieces of merchandise are in stock and can be presented to users as-is, i.e., rendered in the widget. It should be as concise as possible to fit within the widget layout without breaking it. Examples:

"more than 5 pieces in stock"
"last 3 pieces"
“sold out”

`<availability_text>: string (optional)`

Text that briefly indicates when the user can receive the goods. It should be as concise as possible to fit within the widget layout without breaking it. Examples:

"have it today"
"delivery in 3 days"

`<shipped_in_days>: integer (optional)`

Value representing the number of days within which the user can receive the goods. It can be used for promoting items with better availability.

Examples:

0: items can be delivered today
1: items can be delivered tomorrow
7: items can be delivered within a week

`<brand>: string (optional)`

Brand name.

`<brand_id>: string (optional)`

Brand identifier. This should match the brand ID used in the Brand Feed.

`<brand_url>: string (optional)`

Brand landing page URL. This is the same value as <url> in the Brand Feed.

`<brand_image_url>: string (optional)`

Brand icon URL. This is the same value as <image_url> in the Brand Feed.

You can provide brand data in two ways:

Provide <brand>, <brand_url>, and <brand_image_url> directly in the item feed. This is usually fine for smaller catalogues, for example thousands of products and feed sizes in the low tens of MBs.
Provide only <brand_id> in the item feed and keep the full brand metadata in a separate Brand Feed. Consider this when the catalogue is large, for example 50k items or more and feed sizes above 30 MB.

Do not duplicate the same brand metadata in both feeds unless you have a specific reason to do so. Repeating the same brand name, URL, and icon on every item can make the item feed larger and more expensive to download and synchronize.

`<url>: string`

URL of the item page.

`<image_url>: string`

URL of the main item image. It will be used as the main image for Widgets and therefore must be compressed, reasonably sized (neither too large nor too small according to the website layout), and ideally hosted on a CDN or similar for website performance reasons.

Keep in mind that oversized images may negatively impact loading speed, especially on mobile devices with limited bandwidth.

`<image_urls_alt>: object list (optional)`

Alternative item images.

`<add_to_cart_id>: string (optional)`

This optionally represents the ID used when the item is added to a cart.

`<rating>: float (optional)`

Item rating is represented by a float value in the range <0, 1>. For Widget purposes, it will be interpreted accordingly, e.g., in a Widget where the maximum number of stars is 5, 2.5 stars is represented by the value <rating>0.5</rating>.

`<rating_count>: integer (optional)`

Total count of user ratings.

`<age_rating>: integer (optional)`

Minimum age of the user to whom the item can be sold.

`<price>: float`

Actual item price including tax, e.g., 9.99.

`<price_old> : float (optional)`

The price of the item before the discount. It should only be filled in if the item is currently on sale, and if it is on sale, then it should holdprice < price_old.

`<labels>: object list (optional)`

List of item labels, e.g., discount, black friday, new.

Subfields:

<id>: text, unique label ID. If not available, text (below) can be used.
<text>: text, label text, will be displayed in Widgets.
<background_color_hex>: text, background color in hex.
<background_image_url>: text, image URL. Leads to the label image.
<font_color_hex>: text, font color in hex.
<order>: integer. In case of multiple labels, it can determine the order. A label with a smaller value will be rendered before a label with a larger value.

<label>
    <id>top-seller</id>
    <text>Top seller</text>
    <background_color_hex>#fffff</background_color_hex>
    <font_color_hex>#fffff</font_color_hex>
    <order>1</order>
</label>

`<coupons>: object list (optional)`

List of product-applicable coupons.

Subfields:

<id>: text, unique coupon ID. If not available, text (below) can be used.
<text>: text, coupon text, will be displayed in Widgets.
<code>: text, coupon code, will be displayed in Widgets.
<discount_percentage>: text, percentage of discount, will be displayed in Widgets.
<discount_price>: text, discounted price, will be displayed in Widgets.
<background_color_hex>: text, background color in hex.
<background_image_url>: text, image URL. Leads to the coupon image.
<font_color_hex>: text, font color in hex.
<order>: integer. In case of multiple coupons, it can determine the order. A coupon with a smaller value will be rendered before a coupon with a larger value.

<coupon>
    <id>discount-code-top</id>
    <text>discount with code</text>
    <code>TOP</code>
    <discount_percentage>30</discount_percentage>
    <background_color_hex>#fffff</background_color_hex>
    <font_color_hex>#fffff</font_color_hex>
    <order>1</order>
</coupon>

`<categories>: object list`

Represents the categories assigned to the item.

The <category> structure is the same as in the Category Feed. Use the category feed page as the canonical reference for category taxonomy, supported fields, hierarchy models, and examples.

In the item feed:

Many items have one primary category.
An item can belong to multiple categories at the same time.
Order categories by importance in ascending order, with the first category treated as the primary category.
Keep category IDs consistent with your website and with the category feed.

The example below is illustrative only. It shows a single primary category stored directly in the item feed:

<categories>
    <category>
        <id>ps5-games</id>
        <name>PlayStation 5 Games</name>
        <path>Gaming | PlayStation 5 Games</path>
        <url>https://www.eshop.com/gaming/playstation-5-games</url>
        <image_url>https://cdn.eshop.com/categories/ps5-games/icon-200x200.png</image_url>
    </category>
</categories>

You can provide category data in two ways:

Provide the full category data directly in each item's <category> object in the item feed. This is usually fine for smaller catalogues, for example thousands of products and feed sizes in the low tens of MBs.
Provide only category IDs in the item feed and keep names, paths, URLs, icons, and hierarchy definitions in the separate Category Feed. Consider this when the catalogue is large, for example 50k items or more and feed sizes above 30 MB.

Do not duplicate the same category metadata in both feeds unless you have a specific reason to do so. Repeating full category paths and metadata on every item can make the item feed much larger and more expensive to download and synchronize.

When the category feed stores the full taxonomy, the item feed can stay minimal:

<categories>
    <category>
        <id>ps5-games</id>
    </category>
</categories>

`<parameters>: object list`

List of item parameters.

<id>: text, unique parameter ID. If not available, text (below) can be used.
<text>: text, parameter name, which will be rendered on page (e.g., Widget, Search Facet).
<value>: text, parameter value.

<parameters>
    <parameter>
        <id>color</id>
        <text>Barva</text>
        <value>červená</value>
    </parameter>
    <parameter>
        <id>size</id>
        <text>Velikost</text>
        <value>XXL</value>
    </parameter>
</parameters>

`<reviews>: object list` (optional)

List of reviews linked to a particular product.

<review>: text, represents a particular review from a visitor.

`<file>: object list (optional)`

List of arbitrary files (e.g., PDF files with specifications) linked to a particular product.

Within a single <item> entry, each file <id> must be unique. File IDs do not need to be unique across different item entries.

<id>: file identifier
<url>: URL hyperlink representing downloadable file

`<custom>: object (optional)`

Container for custom XML fields not covered by the standard item feed specification.

Use <custom> only for values that:

are not already covered by an existing tag
are not standard item parameters (see <parameters>)

<custom>
    <external_campaign_id>spring-2026</external_campaign_id>
    <region>south-moravia</region>
</custom>

Before adding a field into <custom>, make sure the same information is not already represented by an existing item feed field.

Overview

Categories and brands

Full Example

Individual Tags Documentation

<id>: string

<grouping_id>: string (optional)

<name> : string

<description> : string

<available>: boolean

in_stock_count: integer (optional)

in_stock_text: string (optional)

<availability_text>: string (optional)

<shipped_in_days>: integer (optional)

<brand>: string (optional)

<brand_id>: string (optional)

<brand_url>: string (optional)

<brand_image_url>: string (optional)

<url>: string

<image_url>: string

<image_urls_alt>: object list (optional)

<add_to_cart_id>: string (optional)

<rating>: float (optional)

<rating_count>: integer (optional)

<age_rating>: integer (optional)

<price>: float

<price_old> : float (optional)

<labels>: object list (optional)

<coupons>: object list (optional)

<categories>: object list

<parameters>: object list

<reviews>: object list (optional)

<file>: object list (optional)

<custom>: object (optional)