Categories & Navigation

The storefront uses two separate systems for organizing content: Sales Categories for product taxonomy and Navigation Menus for site navigation.

Sales Categories

Sales categories are the storefront-facing browsing taxonomy. Use them for building category pages, breadcrumbs, and filters.

Get Category Tree

GET /api/storefront/categories
X-Store-Code: us-store
X-Language-Code: en

Returns a hierarchical tree of sales categories with two subtypes:

• Taxonomy — hierarchical product categories (e.g., Shop All → Tops, Bottoms)
• Promotional — cross-cutting collections (e.g., New Arrivals, Sale)

Get Category by ID or Slug

GET /api/storefront/categories/{idOrSlug}
X-Store-Code: us-store
X-Language-Code: en

Accepts a GUID or slug (e.g., s-tops). Returns the category with its children.

Category → Products Flow

Navigation Menus

Navigation menus are flexible, editable structures for building site headers, footers, and sidebars. Unlike categories, menus can link to any URL, category, product, or page.

Get Navigation Menu

GET /api/storefront/navigation/{menuId}
X-Store-Code: us-store
X-Language-Code: en

Response:

{
  "id": "guid",
  "name": "Main Menu",
  "items": [
    {
      "id": "guid",
      "label": "Shop",
      "type": "category",
      "targetId": "category-guid",
      "url": null,
      "children": [
        { "id": "guid", "label": "Tops", "type": "category", "targetId": "guid" },
        { "id": "guid", "label": "Bottoms", "type": "category", "targetId": "guid" }
      ]
    },
    {
      "id": "guid",
      "label": "New Arrivals",
      "type": "category",
      "targetId": "new-arrivals-guid",
      "children": []
    },
    {
      "id": "guid",
      "label": "About Us",
      "type": "url",
      "url": "/about",
      "children": []
    }
  ]
}

Navigation Item Types

Type	Description	How to handle
category	Links to a sales category	Navigate to /c/{slug} or category page
product	Links to a product	Navigate to /product/{slug}
page	Links to a CMS page	Navigate to /page/{slug}
url	Links to any URL	Navigate to the URL directly

Building a Header

tip

Navigation menus are managed in the Backoffice. The menu structure is flexible — items can be nested to any depth and link to different entity types. Build your navigation component to handle this recursively.

Master Category Tree

GET /api/storefront/categories/master
GET /api/storefront/categories/master?tree=false
GET /api/storefront/categories/master?parentId={guid}

The product taxonomy (for example Rings › Diamond Rings), as a tree by default — the counterpart of categories/sales for channels that let customers browse by product type. Same response shape, same store restrictions.

Searching with a master categoryId (POST /api/storefront/products/search) includes the products of all its descendant categories: a product is filed under exactly one master category, usually a leaf, so Rings returns what sits under Rings › Diamond Rings too. childCategories in the response lists the direct sub-categories with their product counts.