Category Feeds

Category feeds describe category pages and the category objects referenced by products. The configured object type is category.

Core fields

Source field	Type	Requirement	Description
id	String	Required	Type-prefixed category identifier, such as category/cat-men.
title	String	Required	Category name shown to users.
url	String	Recommended	Canonical category page URL.
image_url	String	Optional	Category image URL.
parent	String or array	Optional	ID of the category’s immediate parent, such as category/cat-men, mapped to @parent. Omit it on a root category.

Use the same category IDs in parent and in product category references.

Examples

• XML
• JSON
• CSV

<?xml version="1.0" encoding="UTF-8"?>
<categories>
  <category>
    <id>category/cat-men</id>
    <title>Men</title>
    <url>https://example.com/men</url>
  </category>
  <category>
    <id>category/cat-shoes</id>
    <title>Shoes</title>
    <url>https://example.com/men/shoes</url>
    <parent>category/cat-men</parent>
  </category>
</categories>

{
  "categories": [
    {
      "id": "category/cat-men",
      "title": "Men",
      "url": "https://example.com/men"
    },
    {
      "id": "category/cat-shoes",
      "title": "Shoes",
      "url": "https://example.com/men/shoes",
      "parent": "category/cat-men"
    }
  ]
}

id,title,url,parent
category/cat-men,Men,https://example.com/men,
category/cat-shoes,Shoes,https://example.com/men/shoes,category/cat-men

The same records in JSON Lines contain one category object per line:

{"id":"category/cat-men","title":"Men","url":"https://example.com/men"}
{"id":"category/cat-shoes","title":"Shoes","url":"https://example.com/men/shoes","parent":"category/cat-men"}

After mapping, the category-to-parent relationship uses typed references. Other source attributes remain ordinary public catalog attributes:

{
  "@id": "category/cat-shoes",
  "@type": "category",
  "@title": "Shoes",
  "@parent": ["category/cat-men"],
  "url": "https://example.com/men/shoes"
}

Mapping category relationships

Map product category IDs to canonical @category references. These references use stable, typed category IDs. A referenced category can be ingested after the product that refers to it.

See the catalog object model for the canonical relationship format.

Hierarchy

Export each category’s immediate parent, and map it to @parent. Luigi’s Box assembles the tree from those edges, so a category never carries its whole path. See Hierarchies.

Category name paths

For new integrations, link products and categories by ID. An export that names categories by path instead can be linked by name:

<category>
  <id>category/cat-smart-tv</id>
  <title>Smart TV</title>
  <hierarchy>Home &gt; Electronics &gt; TV</hierarchy>
</category>

<product>
  <id>product/sku-2001</id>
  <title>55-inch Smart TV</title>
  <category>Home &gt; Electronics &gt; TV &gt; Smart TV</category>
</product>

The category feed’s mapping gives each category a further name built from its path, a category alias in @aliases, and turns the path into a reference to its parent’s alias:

{
  "@id": "category/cat-smart-tv",
  "@type": "category",
  "@title": "Smart TV",
  "@aliases": ["category/~home/electronics/tv/smart%20tv"],
  "@parent": ["category/~home/electronics/tv"]
}

The product feed’s mapping turns each path into a reference to a category’s alias. Luigi’s Box resolves each reference to the category declaring it, so lbx:category_ids and lbx:category_hierarchy hold your categories’ own IDs:

{
  "@id": "product/sku-2001",
  "@type": "product",
  "@title": "55-inch Smart TV",
  "@category": ["category/~home/electronics/tv/smart%20tv"],
  "lbx:category_ids": ["category/cat-home", "category/cat-electronics", "category/cat-tv", "category/cat-smart-tv"]
}

See Category aliases for how references resolve.

Mapping a category feed

A category feed’s paths follow one of two conventions, and the mapping states which. A child can share its parent’s name (Kids > Shoes > Shoes), so no single record shows it.

When each path names the category’s ancestors only (Home > TV on Smart TV), the alias is the path followed by the category’s title, and the parent is the path:

{
  "@defaults": { "hierarchy": "" },
  "hierarchy": [
    "@parent | split_by_separator('>') |< to_alias",
    "@aliases | split_by_separator('>') |< push(@title) | to_alias"
  ]
}

When each path ends with the category itself (Home > TV > Smart TV on Smart TV), the alias is the path, and the parent is the path without its last name:

{
  "@defaults": { "hierarchy": "@title" },
  "hierarchy": [
    "@parent | split_by_separator('>') |< drop_last | to_alias",
    "@aliases | split_by_separator('>') |< to_alias"
  ]
}

• @defaults gives a root category, which states no path, an alias of its title alone and no parent.
• @title reads the category’s title source field; name your own field if the export calls it differently, such as @name. In the first recipe a category without that field is rejected with mapping_failed.
• In the first recipe the title is one name, never split. A category whose title holds the separator — TV/Audio under / — gets an alias no path matches, since paths are split: neither its products nor its subcategories link to it by path.
• A field holding several paths gives the category one alias and one parent per path.
• Use the same separator in the category and product mappings, written exactly as the feeds write it. See Category aliases for the transforms.

The product feed’s mapping is in Product feeds.

Matching

Rule	Example
Names are compared case-insensitively, and surrounding or repeated whitespace is ignored	home > TV matches Home > TV
The separator is matched exactly as written in the mapping	> matches both Home > TV and Home>TV; ' - ' (space, hyphen, space) keeps T-Shirts as one name
A path is matched whole, from the root	Electronics > TV does not match a category at Home > Electronics > TV

A reference links only when it names exactly one category. A path that matches no category, or one that two categories share, such as Men > Shirts twice, links nothing: the object lists the reference itself in lbx:category_ids, as it lists the ID of a category not indexed yet. A path no category matches links once a category arrives at it; a shared path links once only one category remains at it.

When a category is renamed or moved, its alias changes with its path. Its subcategories and products are linked again as both feeds send their new paths.

A mapping change applies to the records sent after it. Resend both feeds in full once the mappings are in place — see Forcing a full resend.

See also

• Feeds overview
• Catalog object model
• Product feeds
• Feed troubleshooting