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. 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