Catalog

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

Commerce Engine uses a flexible structure to represent your offerings:

1. 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)
   • Variant Indicator: The has_variant flag (boolean) indicates if this product branches into different selectable options (like size or color).
2. Variant (Variant schema):
   • Definition: A specific version of a Product, existing only if the Product’s has_variant flag is true. 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" }).
   • Retrieval: Variants are typically listed via GET /products/{product_id}/variants or retrieved individually via GET /products/{product_id}/variants/{variant_id}.
3. 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 is null if the product has no variants), and potentially a sku (which might be null for 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

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-select or color attributes can be designated for variant creation (by enabling the can_be_used_to_create_variants flag during attribute setup).
  • Behavior: Each unique combination of selected Variant Options results in a separate Variant record. 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:

1. Does this characteristic combination need a unique identifier (SKU) in my warehouse or system?
2. Do I need to track inventory separately for each specific combination (e.g., track stock of ‘Red Large’ shirts separately from ‘Blue Medium’)?
3. Do I need to set different prices, images, or descriptions for specific combinations?
4. 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

• 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. sku is optional (can be null). No inventory tracking (stock_available might 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_id and variant_id/sku) sold as one unit (bundle_items array 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

• Categories (ProductCategory, Category): Hierarchical (parent_category_id) organization. Fetched via GET /catalog/categories.
• Pricing (ProductPricing): Defines listing_price, selling_price, currency, taxes, quantity limits. Variant-specific. Supports B2B customer_group_id overrides.
• Promotions/Offers (on_promotion, on_offer, promotion object): Indicate automatic discounts or available coupons. Variant-specific.
• Reviews (ProductReview, CreateReview): Managed per product_id. Includes ratings, text, images, videos. List via GET /products/{id}/reviews, submit via POST /products/{id}/reviews.
• Related Products (similar, upsell, cross-sell): Endpoints return lists of relevant Item Objects.

​

Catalog API Endpoints (Summary & Key Purpose)

(Endpoint details remain largely the same as the previous version, but the context of what they return and when to use them is refined based on the Product/Variant/Item hierarchy)

• GET /catalog/products: List core products. Use has_variant to know if options exist. Good starting point for PLPs if you handle variant selection/flattening client-side. Contains base info and potentially variant summaries in variants array.
• 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 (if has_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)

Option A: Using GET /catalog/products (Client-side Variant Handling)

1. Call GET /catalog/products with filters (category_id, customer_group_id).
2. Iterate through the products array.
3. For each product:
   • Display common info: name, primary image (images[0]).
   • Check has_variant:
     • If false: Display price from product.pricing. The “Add to Cart” button uses product_id and variant_id: null.
     • If true:
       • Display a price range or the default variant’s price (from product.variants array, find where is_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.variants and add the selected variant_id to the cart.
   • Link to PDP using product.slug or product_id.

Option B: Using GET /catalog/skus (Pre-flattened Items)

1. Call GET /catalog/skus with filters (category_id, customer_group_id). This directly returns sellable Items.
2. Iterate through the items (renamed from skus) array.
3. For each item:
   • Display item.product_name and potentially item.variant_name.
   • Display image (item.images[0]).
   • Display price (item.pricing.selling_price).
   • The “Add to Cart” button uses item.product_id and item.variant_id.
   • Link to the PDP using item.product_id (and potentially pre-select the variant based on item.variant_id).
   • This approach is simpler if you don’t need complex variant selection directly on the PLP card.

​

Displaying a Product Detail Page (PDP)

1. Call GET /catalog/products/{product_id}. Pass customer_group_id if applicable.
2. Render shared Product details: name, description, attributes (attributes), base images/videos, SEO.
3. If product.has_variant is true:
   • Render selection controls (dropdowns, swatches) based on product.variant_options.
   • Call GET /catalog/products/{product_id}/variants to 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 corresponding Variant using its associated_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.
4. If product.has_variant is false:
   • Display pricing, stock status, images directly from the Product object.
   • “Add to Cart” uses product_id and variant_id: null.
5. Fetch and display reviews (GET /products/{id}/reviews).
6. Fetch and display related products (similar, upsell, cross-sell), passing the current product_id.

​

Implementing Search with Facets