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.

Highlights

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.

When the category feed processor is triggered, the categories are ingested.
The categories are processed and stored.
Categories that are not present in the feed are removed.
The latest category data is distributed throughout the Poq Platform.
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 Name	Description	Required	Example
`category-id`	Unique identifier of the category. Must be unique among all categories in the feed.	Required	`dresses-39rq6f`
`category-name`	Display name of the category.	Required	`Dresses`
`parent-category-id`	Identifies the parent category in a nested hierarchy.	Optional	`clothing`
`deep-link`	Deep link to override default category behaviour.	Optional	`category/clothing?sale=true`
`category-url`	Dynamic link URL of the category.	Optional	`https://www.shop.com/clothing/dresses`
`image-url`	Image URL to be displayed against the category.	Optional	`https://cdn.shop.com/dresses.png`
`sort-index`	Sort index of the category in the hierarchy. Lower numbers appear higher in the tree.	Optional	`1`
`custom-field`	Custom values to be included in the Category's Custom Data.	Optional	`Custom Value`

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

Category Feed Example

category-id,category-name,parent-category-id,deep-link,category-url,image-url,sort-index,custom-field
clothing,Clothing,,,https://shop.com/clothing,https://cdn.shop.com/clothing.png,1,custom value
dresses-39rq6f,Dresses,clothing,,https://shop.com/clothing/dresses,https://cdn.shop.com/dresses.png,2,
sale-18jgf2,Sale,clothing,category/clothing?sale=true,https://www.shop.com/clothing?sale=true,,1,

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

FAQ

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

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.