Storefront APIs
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.
Key Catalog Endpoints (Summary & Key Purpose)
GET /catalog/products
: List core products. Usehas_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 invariants
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 (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
Previous
CartThe Carts module provides the APIs to manage a user's shopping cart. It allows you to add, update, and remove items, apply discounts and loyalty points, manage addresses, and retrieve the cart's state before checkout. Commerce Engine carts are persistent and associated with the user (anonymous or logged-in), enabling seamless experiences across sessions or devices.
Next