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.

Use the same category IDs 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>
  </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"
    }
  ]
}

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

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"}

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.

If your export gives each category a full path string instead, the mapping can split it — but the value @parent needs is the nearest ancestor’s typed ID, not the path. See Hierarchies.

Existing hierarchy paths

For new integrations, map products to categories using stable source IDs. If your existing export contains category hierarchy data, agree the mapping during setup.

If you are migrating an existing feed that uses title paths, such as:

Men > Shoes > Sneakers

the delimiter can be configured during mapping so the path is preserved as a structured hierarchy value. The delimiter belongs to the feed mapping, not to the catalog object model.

See also

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