Product Catalog

The product catalog is the core of any storefront. This section covers how to fetch and display products, variants, categories, brands, and attributes.

Products

List Products by Category

GET /api/storefront/products/category/{categoryId}?page=1&pageSize=20&inStockOnly=true
X-Store-Code: us-store
X-Language-Code: en
X-Currency-Code: USD

Response:

{
  "products": [
    {
      "id": "guid",
      "name": "Classic T-Shirt",
      "slug": "classic-t-shirt",
      "brandName": "Urban Thread",
      "categoryName": "Tops",
      "defaultVariant": {
        "id": "guid",
        "sku": "CT-WHT-S",
        "price": 29.99,
        "compareAtPrice": 39.99,
        "imageUrl": "https://api.example.com/media/product-images/ct-white.png"
      },
      "colorVariants": [
        { "color": "#FFFFFF", "colorName": "White", "variantId": "guid", "imageUrl": "..." },
        { "color": "#FF0000", "colorName": "Red", "variantId": "guid", "imageUrl": "..." }
      ],
      "isInStock": true,
      "hasMultipleVariants": true
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 42,
  "totalPages": 3
}

Product Cards

The list endpoint returns display-ready product cards with pre-resolved pricing in the requested currency. You don't need to make separate calls for prices.

Get Product Detail

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

You can pass either a GUID or a slug (e.g., classic-t-shirt). The API resolves slugs via the SlugRegistry.

Response includes:

• Full product details (name, description, specifications)
• All variants with their configurations, prices, images, and stock status
• Attribute options for building variant selectors (color swatches, size dropdowns)

Search Products

GET /api/storefront/products/search?q=t-shirt&page=1&pageSize=20
X-Store-Code: us-store
X-Language-Code: en
X-Currency-Code: USD

The search endpoint supports full-text search across product names, descriptions, SKUs, and attribute values.

Categories

Get Category Tree

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

Returns the Sales category tree (not master categories). The tree is hierarchical:

[
  {
    "id": "guid",
    "name": "Shop All",
    "slug": "s-shop-all",
    "salesCategoryType": "Taxonomy",
    "children": [
      { "id": "guid", "name": "Tops", "slug": "s-tops", "children": [] },
      { "id": "guid", "name": "Bottoms", "slug": "s-bottoms", "children": [] },
      { "id": "guid", "name": "Dresses", "slug": "s-dresses", "children": [] }
    ]
  },
  {
    "id": "guid",
    "name": "New Arrivals",
    "slug": "s-new-arrivals",
    "salesCategoryType": "Promotional",
    "children": []
  }
]

Get Single Category

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

Accepts GUID or slug. Returns the category with its child categories.

Brands

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

Returns all brands with localized names.

Building a Variant Selector

When displaying a product detail page, you need to let users pick a variant (e.g., Color + Size). Here's the recommended approach:

Algorithm:

1. From the product's variants, extract all unique Attribute → AttributeValue combinations
2. Render the first attribute (e.g., Color) as swatches
3. When the user selects a value, filter remaining variants and show available options for the next attribute
4. Once all attributes are selected, find the exact variant match
5. Display that variant's price, images, and stock status
6. Use that variant's id when adding to basket

Availability Check

GET /api/storefront/availability/{productVariantId}
X-Store-Code: us-store

Returns stock availability for a specific variant in the current store's warehouses.

{
  "isAvailable": true,
  "quantity": 15
}