Catalog Architecture
Why catalog structure matters
Section titled “Why catalog structure matters”A flat list of products breaks down the moment your store grows past a few dozen items. Customers cannot browse efficiently, marketers cannot merchandise by season or audience, and developers cannot build faceted navigation or dynamic landing pages. Without a deliberate hierarchy, every team improvises, and the storefront becomes inconsistent.
Optimizely Commerce solves this with a four-level catalog hierarchy that separates organizational concerns from sellable concerns. The structure gives marketers browsable categories, gives developers predictable data shapes, and gives operations teams clear SKU-level tracking.
The four-level hierarchy
Section titled “The four-level hierarchy”Commerce organizes sellable items into four distinct levels, each with a specific role.
| Level | Purpose | Example |
|---|---|---|
| Catalog | Top-level container that groups an entire product line or storefront | ”B2B Industrial Supplies”, “Consumer Storefront 2026” |
| Category | Organizational node for navigation and merchandising | ”Power Tools”, “Safety Equipment”, “Fasteners” |
| Product | A conceptual item that represents what you sell | ”Cordless Drill Model X200” |
| Variant | The specific purchasable SKU with unique price and inventory | ”X200 - Blue, 18V”, “X200 - Red, 24V” |
Categories can nest to any depth. A “Power Tools” category might contain “Drills”, “Saws”, and “Sanders” as subcategories. Products sit at the leaf level and always contain at least one variant.
Why variants are separate from products
Section titled “Why variants are separate from products”Customers think in terms of products. They want “that drill.” But your warehouse, pricing engine, and order system think in terms of SKUs. A single product might have dozens of variants across size, color, voltage, or region. Separating the two lets marketing describe the product once while operations tracks each variant independently.
This separation also prevents combinatorial explosion in your catalog UI. Instead of creating a separate product entry for every color-size combination, you define variation axes on the product and let Commerce generate the variant matrix.
Metadata and custom properties
Section titled “Metadata and custom properties”Every level in the hierarchy carries metadata. Categories have descriptions and images for navigation pages. Products carry marketing copy, specification sheets, and SEO fields. Variants hold SKU codes, weight, dimensions, and any attribute that differs between purchasable options.
Configured vs Customized catalog models
Section titled “Configured vs Customized catalog models”The two editions handle catalog extensibility differently.
| Capability | Configured | Customized |
|---|---|---|
| Adding fields to products | Admin UI property editor | Code-defined content types |
| Custom product types | Predefined templates with optional fields | Unlimited custom types inheriting from base classes |
| Category nesting | Unlimited depth via UI | Unlimited depth via UI or API |
| Variant generation | Automatic from defined axes | Manual or automatic via custom logic |
| Import/export | Built-in CSV and feed support | API-driven with custom transform pipelines |
Choose Configured when your catalog follows standard retail patterns. Move to Customized when you need computed properties, cross-variant logic, or catalog structures that do not map to the built-in templates.
Multi-catalog strategies
Section titled “Multi-catalog strategies”Commerce supports multiple catalogs within a single site. Common patterns include:
- Regional catalogs — Separate product lines for different markets, each with localized content and currency-specific pricing
- Channel catalogs — One catalog for the public storefront, another for the B2B portal, sharing some products but with different visibility rules
- Seasonal catalogs — Time-bound collections that activate and deactivate on schedule without disrupting the main catalog
Products can belong to categories across catalogs, which avoids duplicating product data when the same item appears in multiple storefronts.
How catalog data flows to the storefront
Section titled “How catalog data flows to the storefront”The catalog is not just a database. It feeds into search indexing, pricing resolution, inventory checks, and content rendering. When a product changes, Commerce publishes events that downstream systems consume. Search indexes rebuild, cached pages invalidate, and pricing recalculates.
This event-driven approach means catalog updates propagate without manual cache clearing or redeployment. It also means you should design your custom properties with indexing in mind — every field you add to a product potentially becomes a searchable facet or a filter in your navigation.
Common pitfalls
Section titled “Common pitfalls”- Too-flat hierarchies — Putting all products in one category defeats browsing and merchandising. Use at least two levels of categorization.
- Variant overuse — If two items share nothing but a brand name, they are separate products, not variants. Variants should differ only in purchasable attributes like size or color.
- Ignoring the product level — Skipping straight from category to variant loses the grouping that powers product comparison, cross-sell, and search result clustering.
1. A customer wants to sell the same physical product on both a B2C storefront and a B2B portal with different visibility rules. What catalog strategy should they use?
Multi-catalog with shared product references avoids data duplication while allowing different visibility and pricing per channel.
Multi-catalog with shared product references avoids data duplication while allowing different visibility and pricing per channel.
Review this topic →2. Why does Commerce separate products from variants instead of treating each SKU as its own product?
The product-variant separation lets marketing manage a single product description while each variant carries its own SKU, price, and inventory independently.
The product-variant separation lets marketing manage a single product description while each variant carries its own SKU, price, and inventory independently.
Review this topic →3. An architect notices that catalog updates are not appearing in search results. What is the most likely architectural cause?
Commerce uses event-driven propagation for catalog changes. If custom properties are not configured for indexing, search results will not reflect updates.
Commerce uses event-driven propagation for catalog changes. If custom properties are not configured for indexing, search results will not reflect updates.
Review this topic →