2 min read

Category Feed Integration

To keep your app's shop screen up-to-date with your latest category hierarchy, you need to provide a single CSV file which Poq uses to populate your navigation tree. This file is called the Category feed file.

Your category feed file contains all the information required to help your customer navigate categories to find products.

In order to keep your app up to date, it is recommended to process this data regularly. To enable your category feed to run on a schedule, please contact support@poqcommerce.com.


  • Categories can be defined separately to the Product Feed.
  • Category functionality can be expanded via Deep Links.
  • Categories can be edited via the App Manager.
  • Changes made to categories persist between feed runs.
  • Custom Data can be leveraged for custom integrations.

How Navigation Works

  1. When the category feed processor is triggered, the categories are ingested.
  2. The categories are processed and stored.
  3. Categories that are not present in the feed are removed.
  4. The latest category data is distributed throughout the Poq Platform.
  5. The Category hierarchy is constructed and sent to the app when it is requested.

Creating Your Category Hierarchy

Your app's category hierarchy can be imported into the Poq Platform via the category feed processor. This feed file should be separate from your product feed file.

Category Feed Specification

Field NameDescriptionRequiredExample
category-idUnique identifier of the category. Must be unique among all categories in the feed.Requireddresses-39rq6f
category-nameDisplay name of the category.RequiredDresses
parent-category-idIdentifies the parent category in a nested hierarchy.Optionalclothing
deep-linkDeep link to override default category behaviour.Optionalcategory/clothing?sale=true
category-urlDynamic link URL of the category.Optionalhttps://www.shop.com/clothing/dresses
image-urlImage URL to be displayed against the category.Optionalhttps://cdn.shop.com/dresses.png
sort-indexSort index of the category in the hierarchy. Lower numbers appear higher in the tree.Optional1
custom-fieldCustom values to be included in the Category's Custom Data.OptionalCustom Value

Note: Custom field headers can take any name other than the fields names specified above.

Category Feed Example

clothing,Clothing,,,https://shop.com/clothing,https://cdn.shop.com/clothing.png,1,custom value

The above category feed would create the following category hierarchy:

"id": "clothing",
"name": "Clothing",
"categoryUrl": "https://www.shop.com/clothing",
"imageUrl": "https://cdn.shop.com/clothing.png",
"sortIndex": 1,
"categories": [
"id": "sale-18jgf2",
"name": "Sale",
"parentCategoryId": "clothing",
"deepLink": "category/clothing?sale=true",
"categoryUrl": "https://www.shop.com/clothing?sale=true",
"sortIndex": 1
"id": "dresses-39rq6f",
"name": "Dresses",
"parentCategoryId": "clothing",
"categoryUrl": "https://www.shop.com/dresses",
"imageUrl": "https://cdn.shop.com/dresses.png",
"sortIndex": 2
"customData": {
"custom-field": "custom value"


What happens if a Child Category's Parent does not exist?

The child category will not appear in the hierarchy. If the parent is added at a later date, it will appear as normal.

What should my Category ID be? Should it match the Category ID in the legacy Poq Platform?

The Category ID can be any value that uniquely identifies a category. It is not constrained by the legacy Poq Platform.

Glossary of Terms


A navigation entity that directs customers to a set of similarly grouped products.

Category Hierarchy

A structured list of categories that contain root categories, Branch categories, and leaf categories. Allows for granular navigation through the product catalogue.

Root Category

A category that appears at the root of the category hierarchy. They do not have a parent category and create the entry point for customer navigation. Both branch and leaf categories can be a root category.

Branch Category

A category that has child categories beneath it. They direct to their list of child categories, instead of a set of a products.

Leaf Category

The final entity of a path within a category hierarchy. Does not have any child categories. Directs to a set of products.

Parent/Child Category

A parent category is any category that is structured above a set of categories. The child category is any category that is structured below a single category. A category can be both a parent and a child.