Storefront Guides
Catalog
Storefront Guides
Catalog
The Catalog module is the cornerstone of your Commerce Engine storefront. It defines everything you sell – products, their variations, how they’re organized, priced, and described. Mastering these APIs allows you to build compelling product listings, detailed descriptions, category navigation, powerful search, customer reviews, and insightful recommendations.
Key Features Covered:
- Flexible Product Modeling: Handles simple products, products with options (variants), digital goods, and bundled items.
- Products, Variants, and Items: Clear structure distinguishing the core product concept from its specific sellable variations (Items).
- Rich Attributes: Define characteristics for filtering, display, and variant creation (Color, Size, Brand, etc.).
- Hierarchical Categories: Organize your catalog for easy navigation.
- Engaging Content: Support for multiple images, videos, detailed descriptions, and SEO metadata per product and variant.
- Dynamic Pricing & B2B: Define base prices, handle taxes, and set specific prices/promotions for different Customer Groups.
- Inventory & Promotions: Real-time stock availability and flags for active promotions/offers on specific Items.
- Integrated Reviews: List and capture customer reviews with ratings, text, images, and videos.
- Product Recommendations: APIs for similar, upsell, and cross-sell suggestions.
- Faceted Search: Robust search powered by product attributes.
Core Concepts
Grasping these foundational models is essential for leveraging the Catalog API effectively.The Product-Variant-Item Hierarchy
The Product-Variant-Item Hierarchy
Commerce Engine uses a flexible structure to represent your offerings:
Product (Product schema):- Definition: The core concept or base model of an item you sell (e.g., “Men’s Cotton T-Shirt”, “Espresso Machine”, “Beginner’s Yoga Course”).
- Shared Data: Holds information common across all its potential variations:
- Base Name (
name) - Product Type (
product_type: physical, digital, bundle) - HSN Code (
hsn_code) - Categories (
category_ids) - Tags (
tags) - Base Attributes (
attributes): Characteristics shared by all variations (e.g., ‘Brand’, ‘Material’). - Base SEO (
seo)
- Base Name (
- Variant Indicator: The
has_variantflag (boolean) indicates if this product branches into different selectable options (like size or color).
Variant (Variant schema):- Definition: A specific version of a Product, existing only if the Product’s
has_variantflag istrue. It represents a unique combination of selected Variant Options (e.g., “Men’s Cotton T-Shirt - Blue / Large”). - Specific Data: While conceptually linked to the parent Product, a Variant holds its own specific details for:
- SKU (
sku) - The warehouse identifier for this specific variation. - Name (
name) - Often includes option values (e.g., “T-Shirt - Red, Large”). - Slug (
slug) - Descriptions (
short_description,description) - Images (
images) - Can override or supplement Product images. - Videos (
videos) - Pricing (
pricing) - Subscription Pricing (
subscription) - Promotions (
promotion) - Inventory (Stock is tracked per Variant)
- Shipping Details (
shipping) - Packaging Details (Managed via Admin/other APIs)
- Variant Attributes (
variant_attributes) - Attributes specific only to this variant. - Associated Options (
associated_options) - Links back to the specific option values (e.g.,{ "color": "Blue", "size": "Large" }).
- SKU (
- Retrieval: Variants are typically listed via
GET /products/{product_id}/variantsor retrieved individually viaGET /products/{product_id}/variants/{variant_id}.
- Definition: A specific version of a Product, existing only if the Product’s
Item (Item/SKU schema - Note: To be renamed from SKU in future spec):- Definition: This represents the uniquely identifiable, sellable unit that a customer ultimately adds to their cart and purchases. It’s the lowest level of granularity for a purchasable entity.
- Structure: Contains
product_id,variant_id(which isnullif the product has no variants), and potentially asku(which might benullfor digital products or bundles). It aggregates relevant details needed for display and purchase (name, pricing, image, stock status, attributes, etc.) from either the Product (if no variants) or the specific Variant. - Usage: APIs like
GET /catalog/skus,POST /catalog/products/search, and the related products endpoints (similar,upsell,cross-sell) return lists of these flattened Item Objects. This simplifies building listings (PLPs, search results) where you need a direct list of things to buy.
Attributes vs. Variant Options
Attributes vs. Variant Options
This is a critical distinction in Commerce Engine:
Attributes (ProductAttribute schema & its types):- Purpose: Primarily used to enrich product or variant data, provide filtering capabilities (search facets), and display specifications.
- Types: Color, Single-Select, Multi-Select, Text, Date, Number, Boolean.
- Behavior: Generally, attributes do not create separate inventory tracking or fundamentally change the sellable item. They add metadata.
- Configuration: Defined in the Admin UI with flags like
is_filterable,is_visible.
Variant Options (VariantOption schema, associated_options in Variant):- Purpose: Used to logically branch a product into distinct, sellable Variants.
- Eligible Attribute Types: Only
single-selectorcolorattributes can be designated for variant creation (by enabling thecan_be_used_to_create_variantsflag during attribute setup). - Behavior: Each unique combination of selected Variant Options results in a separate
Variantrecord. This allows for unique SKUs, inventory tracking, pricing, images, etc., per combination. - Example: A “T-Shirt” Product might use “Size” (single-select) and “Color” (color) attributes as Variant Options. This creates Variants like “T-Shirt - Red, Small”, “T-Shirt - Blue, Large”, each potentially having its own stock level and image.
Decision Guide: Variant Option vs. Attribute?Ask these questions when defining a product characteristic:
- Does this characteristic combination need a unique identifier (SKU) in my warehouse or system?
- Do I need to track inventory separately for each specific combination (e.g., track stock of ‘Red Large’ shirts separately from ‘Blue Medium’)?
- Do I need to set different prices, images, or descriptions for specific combinations?
- Do customers need to explicitly select this characteristic combination to add the item to their cart?
If YES to any of these, use a single-select or color attribute and enable can_be_used_to_create_variants to make it a Variant Option.If NO, use a standard Attribute for enrichment, filtering, or display purposes (e.g., ‘Material’, ‘Brand’, ‘Country of Origin’, ‘Features’).Product Types Explained
Product Types Explained
- Physical: Tangible goods needing shipping. Can have variants. Have SKUs, inventory tracking, shipping details.
- Digital: Non-tangible goods (e-books, software, courses). Can have variants.
skuis optional (can benull). No inventory tracking (stock_availablemight always be true or managed differently). No shipping/packaging details. Often use subscription pricing. - Bundle: A logical grouping of existing Items (defined by their
product_idandvariant_id/sku) sold as one unit (bundle_itemsarray in Product schema).- Cannot have variants.
- No unique SKU or inventory: Stock status depends entirely on the availability of all included items.
- Has its own Product record for name, descriptions, pricing (often discounted), promotions, images, videos, SEO.
- Shipping/packaging is implicitly derived from the constituent physical items.
Other Key Concepts
Other Key Concepts
Categories (ProductCategory, Category):Hierarchical (parent_category_id) organization. Fetched viaGET /catalog/categories.Pricing (ProductPricing):Defineslisting_price,selling_price, currency, taxes, quantity limits. Variant-specific. Supports B2Bcustomer_group_idoverrides.Promotions/Offers (on_promotion, on_offer, promotion object):Indicate automatic discounts or available coupons. Variant-specific.Reviews (ProductReview, CreateReview):Managed perproduct_id. Includes ratings, text, images, videos. List viaGET /products/{id}/reviews, submit viaPOST /products/{id}/reviews.Related Products (similar, upsell, cross-sell):Endpoints return lists of relevant Item Objects.
Key Catalog Endpoints (Summary & Key Purpose)
GET /catalog/products: List core products. Usehas_variantto know if options exist. Good starting point for PLPs if you handle variant selection/flattening client-side. Contains base info and potentially variant summaries invariantsarray.GET /catalog/skus: List flattened, sellable Items. Ideal for PLPs or inventory checks where you need a direct list of purchasable units, bypassing product hierarchy.GET /catalog/products/{product_id}: Get full details for a single Product, including shared data, attributes, and variant options/summaries. Core for PDPs.GET /catalog/products/{product_id}/variants: List all specific Variants for a product (ifhas_variant: true). Provides variant-specific details (pricing, SKU, images).GET /catalog/products/{product_id}/variants/{variant_id}: Get full details for one specific Variant.GET /catalog/categories: Fetch category tree for navigation.GET /catalog/products/{product_id}/reviews: List reviews for a product.POST /catalog/products/{product_id}/reviews: Submit a review (requires logged-in user, order number).GET /catalog/products/similar: Get similar Items.GET /catalog/products/up-sell: Get upsell Items.GET /catalog/products/cross-sell: Get cross-sell Items.POST /catalog/products/search: Search returns a list of matching Items, plus facet data for filtering.
Common Use Cases & Flows
Displaying a Product Listing Page (PLP)
Displaying a Product Listing Page (PLP)
Option A: Using GET /catalog/products (Client-side Variant Handling)- Call
GET /catalog/productswith filters (category_id,customer_group_id). - Iterate through the
productsarray. - For each product:
- Display common info:
name, primary image (images[0]). - Check
has_variant:If false:Display price fromproduct.pricing. The “Add to Cart” button usesproduct_idandvariant_id: null.If true:- Display a price range or the default variant’s price (from
product.variantsarray, find whereis_default: true). - The “Add to Cart” button might need to direct to the PDP for option selection, OR you could potentially render simple variant selectors (e.g., color swatches) directly on the card using data from
product.variantsand add the selectedvariant_idto the cart.
- Display a price range or the default variant’s price (from
- Link to PDP using
product.slugorproduct_id.
- Display common info:
Option B: Using GET /catalog/skus (Pre-flattened Items)- Call
GET /catalog/skuswith filters (category_id,customer_group_id). This directly returns sellable Items. - Iterate through the
items(renamed fromskus) array. - For each item:
- Display
item.product_nameand potentiallyitem.variant_name. - Display image (
item.images[0]). - Display price (
item.pricing.selling_price). - The “Add to Cart” button uses
item.product_idanditem.variant_id. - Link to the PDP using
item.product_id(and potentially pre-select the variant based onitem.variant_id). - This approach is simpler if you don’t need complex variant selection directly on the PLP card.
- Display
Displaying a Product Detail Page (PDP)
Displaying a Product Detail Page (PDP)
- Call
GET /catalog/products/{product_id_or_slug}. Passcustomer_group_idif applicable. - Render shared Product details:
name,description, attributes (attributes), base images/videos, SEO. If product.has_variant is true:- Render selection controls (dropdowns, swatches) based on
product.variant_options. - Call
GET /catalog/products/{product_id}/variantsto fetch all variant data upfront or implement logic to fetch/update details (price, image, SKU, stock status, variant-specific description/attributes) dynamically as the user selects options. Map selected options to the correspondingVariantusing itsassociated_options. - Enable “Add to Cart” only when a valid variant combination is selected. Use the selected
variant_id. - Display variant-specific pricing, images, stock status.
- Render selection controls (dropdowns, swatches) based on
If product.has_variant is false:- Display pricing, stock status, images directly from the
Productobject. - “Add to Cart” uses
product_idandvariant_id: null.
- Display pricing, stock status, images directly from the
- Fetch and display reviews (
GET /products/{id}/reviews). - Fetch and display related products (
similar,upsell,cross-sell), passing the currentproduct_id.
Implementing Search with Facets
Implementing Search with Facets