Category Feed

Use the category feed to provide category records that Search can index, link to category landing pages, and display with icons.

When to provide a category feed

Provide a separate category feed when categories should be managed as a shared taxonomy outside the item feed.

This is usually the right choice when:

• your item feed contains only category IDs and not full category names, paths, URLs, or icons
• the same category metadata would otherwise be repeated on many items and make the item feed unnecessarily large
• you want Search to work with category names, hierarchy paths, landing page URLs, or icons from one central taxonomy source
• you want to update category metadata separately from product data

You usually do not need a separate category feed when:

• the item feed already contains complete category metadata for each item
• the catalogue is small enough that repeating category data in the item feed is acceptable
• there is no need to manage category names, paths, URLs, or icons separately

Which categories to provide

If your source system has internal categories that differ from the categories shown on the website, provide the web-facing categories if possible.

This situation is common, for example:

• ERP, PIM, or other backend systems use categories designed for operations rather than for website navigation
• historical internal categories no longer match the current website structure
• one website category is assembled from multiple internal categories

Web-facing categories are the correct source whenever they are available, because they match what users actually see on the website:

• category landing pages and URLs
• visible category names and hierarchy paths
• the browse structure that product and category context should follow

In most integrations, keep the taxonomy that already exists on the website. This avoids an extra mapping layer and usually makes the integration easier to validate and debug.

Typical reasons to simplify or remap categories:

• the source taxonomy is too deep or noisy for Search
• the source system contains technical or internal-only categories
• multiple source categories should behave as one category in Perselio

If only internal categories are available, or if you deliberately simplify the taxonomy for Perselio, keep the mapping consistent across the item feed, category feed, and the taxonomy exposed on the website. Otherwise, web and feed data can drift apart and category issues become harder to debug.

What Perselio uses this feed for

When a category feed is provided, Perselio can use it to:

• search in category names and hierarchy paths
• forward a category result to the category landing page
• show an icon for the category
• keep category metadata in one place instead of repeating it across many items

Category feed structure

Wrap the feed in a <perselio_category_feed> root element and add one <category> element for each category you want search to use.

Use category IDs that match the item feed and website taxonomy when possible. The category ID should ideally match the category ID that appears on the website, such as in HTML markup or the category page URL. If you simplify or remap categories for Perselio, use that adjusted ID consistently in both the item feed and the category feed.

The <category> structure is the same as the category object inside the item feed (<categories><category>). Keep the detailed taxonomy documentation on this page and link to it from the item feed.

Category XML model

Each <category> element defines one category record in the XML feed.

How item categories should map to the category feed

Use the same taxonomy in the category feed, the item feed , and the website whenever possible.

You can keep full category data directly in the item feed or provide only category IDs there and keep the full category model in the category feed. If your catalogue is small, for example, thousands of products and a feed size in the low tens of MBs, keeping category data only in the item feed is usually fine. If your catalogue is large, for example, 50k items or more, and feed sizes above 30 MB, consider a separate category feed so you do not repeat category paths and metadata on every item.

Do not duplicate the same category metadata in both feeds unless you have a specific reason to do so.

When you assign categories to an item:

• Many items have one primary category, but items can also belong to multiple categories when that reflects real browse paths on the website.
• Order categories by importance in ascending order, with the first category treated as the primary category.
• Keep category IDs consistent across the website, item feed, and category feed.

Perselio supports both common ID models:

• leaf/page IDs, where only the final category landing pages have records
• node IDs, where intermediary categories such as Women or Women | Shoes also have records

If you keep your existing taxonomy as-is, choose the model that already matches your website and source system. If you simplify the taxonomy for Perselio, choose the model that best fits the intended Search behavior.

The examples below are illustrative. They show supported category models, not a requirement to redesign your website taxonomy.

Example: straightforward single-path taxonomy

In this model, each category represents one landing page and has one hierarchy path. This is common when the existing website taxonomy is already straightforward, or when a simplified Perselio taxonomy intentionally uses one path per category.

<?xml version="1.0"?>
<perselio_category_feed>
    <category>
        <id>running-shoes</id>
        <name>Running Shoes</name>
        <path>Shoes | Running Shoes</path>
        <url>https://eshop.com/shoes/running-shoes</url>
        <image_url>https://cdn.eshop.com/categories/running-shoes/icon-200x200.png</image_url>
    </category>
    <category>
        <id>hiking-boots</id>
        <name>Hiking Boots</name>
        <path>Shoes | Hiking Boots</path>
        <url>https://eshop.com/shoes/hiking-boots</url>
        <image_url>https://cdn.eshop.com/categories/hiking-boots/icon-200x200.png</image_url>
    </category>
</perselio_category_feed>

This setup is often sufficient when:

• Each category has one clear landing page
• Search mainly needs to work with end categories
• You do not need dedicated IDs for intermediary nodes such as Shoes

Example: one category in multiple hierarchies

Use multiple <path> tags only when the same category landing page genuinely belongs to more than one hierarchy. A typical case is a category that can be reached from both a gender-based tree and an activity-based tree.

<?xml version="1.0"?>
<perselio_category_feed>
    <category>
        <id>running-shoes</id>
        <name>Running Shoes</name>
        <path>Women | Shoes | Running Shoes</path>
        <path>Sports | Running Gear | Running Shoes</path>
        <url>https://eshop.com/running-shoes</url>
        <image_url>https://cdn.eshop.com/categories/running-shoes/icon-200x200.png</image_url>
    </category>
</perselio_category_feed>

In this model:

• Keep the same id when both paths lead to the same category page
• Add another category record only if it is a different landing page with a different ID
• Avoid using temporary campaign paths as taxonomy unless they are real category pages

Example: intermediary nodes have their own IDs

Use this model when Search or widgets need to filter, facet, or promote items at intermediary levels such as Women or Women | Shoes.

<?xml version="1.0"?>
<perselio_category_feed>
    <category>
        <id>women</id>
        <name>Women</name>
        <path>Women</path>
        <url>https://eshop.com/women</url>
        <image_url>https://cdn.eshop.com/categories/women/icon-200x200.png</image_url>
    </category>
    <category>
        <id>women-shoes</id>
        <name>Shoes</name>
        <path>Women | Shoes</path>
        <url>https://eshop.com/women/shoes</url>
        <image_url>https://cdn.eshop.com/categories/women-shoes/icon-200x200.png</image_url>
    </category>
    <category>
        <id>running-shoes</id>
        <name>Running Shoes</name>
        <path>Women | Shoes | Running Shoes</path>
        <url>https://eshop.com/women/shoes/running-shoes</url>
        <image_url>https://cdn.eshop.com/categories/running-shoes/icon-200x200.png</image_url>
    </category>
</perselio_category_feed>