Product-Category Mapping

Assign products to categories to organize your storefront and enable category-based navigation.

---

Mapping Products to a Category

1. Go to Admin → Categories → click a category
2. Go to the Products tab
3. Toggle products on or off

Each product can belong to multiple categories. Changes save immediately.

---

API Endpoint

The mapping endpoint returns all products with an isMappedToCategory flag:

GET /api/v1/{storePublicId}/categories/{categoryId}/products

Response:

{
  "content": [
    {
      "id": "...",
      "name": "Product Name",
      "isMappedToCategory": true
    }
  ]
}

isMappedToCategory: true means the product is assigned to this category. This enables a checkbox UI — show all products and let the user toggle which ones belong to the category.

---

Category Page on Storefront

On the storefront, a category page shows both subcategories and products:

// Automatic slug detection from URL: /categories/shoes
<Category>
  <CategoryImage class="w-full aspect-square object-cover" />
  <CategoryName class="text-2xl font-bold" />

  {/* Subcategories */}
  <SubcategoryList>
    <Grid cols={3} gap={4}>
      <CategoryListView>
        <Category>
          <CategoryImage />
          <CategoryName />
        </Category>
      </CategoryListView>
    </Grid>
  </SubcategoryList>

  {/* Products in this category */}
  <ProductList>
    <Grid cols={4} gap={4}>
      <CollectionView>
        <Product>
          <ProductImage />
          <ProductName />
          <ProductPrice />
        </Product>
      </CollectionView>
    </Grid>
  </ProductList>
</Category>

ProductList inside a <Category> context automatically filters products by that category — no categoryId prop needed.

---

Adding Products to Subcategories

You can add products to category subcategories atomically:

POST /api/v1/{storePublicId}/categories/{categoryId}
{
  "addProducts": ["product-id-1", "product-id-2"],
  "removeProducts": ["product-id-3"]
}

Operations are all-or-nothing and include version checking for optimistic concurrency control.

---

Adding Subcategories to a Category

Similarly, you can manage which categories are children of a parent:

POST /api/v1/{storePublicId}/categories/{categoryId}
{
  "addChildren": ["child-category-id-1", "child-category-id-2"],
  "removeChildren": ["child-category-id-3"]
}