Dynamic Categories

Dynamic categories allow you to create category pages that automatically display products matching saved search criteria, without manually assigning products to the category.

What Are Dynamic Categories?

A dynamic category is a category linked to a saved search. Instead of displaying products that have the category assigned to them, it displays products that match the saved search criteria.

This enables:

• Automatic product collections (no manual assignment needed)
• Real-time product lists that update as products change
• Complex filtering criteria without product modifications

How It Works

The savedSearchId Property

Categories have a savedSearchId property that links them to a saved product search:

{
  "categoryId": "new-arrivals",
  "name": "New Arrivals",
  "savedSearchId": "search-new-products-30-days",
  "parentId": "catalog"
}

When savedSearchId is set:

• The category acts as a "virtual" category
• Products displayed come from the saved search, not from category assignments
• Product counts reflect the saved search results

Saved Search

A saved search stores product search criteria:

{
  "id": "search-new-products-30-days",
  "name": "Products created in last 30 days",
  "searchRequest": {
    "createdFrom": "now-30d",
    "isActive": true,
    "sortOrder": "createdDescending"
  }
}

Use Cases

New Arrivals

Display products created recently without manually tagging them:

Saved Search:

{
  "id": "new-arrivals-search",
  "searchRequest": {
    "createdFrom": "now-30d",
    "isActive": true,
    "sortOrder": "createdDescending"
  }
}

Category:

{
  "categoryId": "new-arrivals",
  "name": "New Arrivals",
  "savedSearchId": "new-arrivals-search"
}

On Sale

Display products with active promotions or discounted prices:

Saved Search:

{
  "id": "on-sale-search",
  "searchRequest": {
    "hasPromotion": true,
    "isActive": true
  }
}

Category:

{
  "categoryId": "sale",
  "name": "On Sale",
  "savedSearchId": "on-sale-search"
}

Best Sellers

Display top-selling products based on sales data:

Saved Search:

{
  "id": "best-sellers-search",
  "searchRequest": {
    "isActive": true,
    "sortOrder": "popularityDescending",
    "take": 100
  }
}

Category:

{
  "categoryId": "best-sellers",
  "name": "Best Sellers",
  "savedSearchId": "best-sellers-search"
}

Brand Collections

Display all products from a specific brand:

Saved Search:

{
  "id": "acme-brand-search",
  "searchRequest": {
    "brand": "Acme",
    "isActive": true
  }
}

Category:

{
  "categoryId": "acme-collection",
  "name": "Acme Collection",
  "savedSearchId": "acme-brand-search"
}

Setting Up Dynamic Categories

Step 1: Create the Saved Search

Create a saved search with your desired criteria via the Omnium UI or API:

POST /api/savedsearches
Content-Type: application/json
 
{
  "name": "Summer Collection",
  "searchRequest": {
    "season": "Summer 2024",
    "isActive": true
  }
}

Note the returned id for the saved search.

Step 2: Create or Update the Category

Create a category with the savedSearchId property:

POST /api/productcategories
Content-Type: application/json
 
{
  "categoryId": "summer-collection",
  "name": "Summer Collection",
  "language": "en",
  "parentId": "seasonal",
  "savedSearchId": "search-id-from-step-1"
}

Step 3: Verify

The category now displays products from the saved search. Test by:

1. Viewing the category in the Omnium UI
2. Fetching products via the category tree API
3. Verifying product counts match expectations

Important Considerations

No Manual Assignment

Products in dynamic categories are not assigned to the category:

• Products don't have the category in their categoryIds
• The relationship is defined by the search criteria only
• Changing the saved search immediately changes which products appear

Category Tree Behavior

Dynamic categories appear in the category tree with product counts based on the saved search:

{
  "categoryId": "new-arrivals",
  "name": "New Arrivals",
  "productCount": 45,
  "savedSearchId": "new-arrivals-search"
}

Parent Category Addition

When isProductCategoryParentsAdded is enabled, products in dynamic categories do not automatically get the dynamic category or its parents added to their categoryIds. The relationship remains virtual.

Combining Static and Dynamic

A category can have either:

• Manually assigned products (no savedSearchId)
• Dynamic products from a saved search (savedSearchId set)

You cannot combine both. If savedSearchId is set, manual assignments are ignored for display purposes.

Performance

Dynamic categories execute the saved search query each time products are requested. For frequently accessed categories:

• Keep saved search criteria efficient
• Consider caching if available
• Monitor query performance

Limitations

Removing Dynamic Behavior

To convert a dynamic category back to a static category:

PUT /api/productcategories
Content-Type: application/json
 
{
  "categoryId": "new-arrivals",
  "name": "New Arrivals",
  "language": "en",
  "savedSearchId": null
}

After removing savedSearchId, products will need to be manually assigned to the category to appear.