Product catalog overview

Ask about this Page
Copy for AI
View as Markdown

Overview of the concepts related to the Product catalog of your Project.

The product catalog is the central location where you can manage all your Product data definitions and sellable items. It acts as the foundation for your retail offerings.

This central repository lets you:

Learn more about Product Types in our self-paced Product data modeling and Advanced Product data modeling modules.

Definitions

Product

A Product acts as a parent structure for Product Variants that are the actual sellable units (SKUs). Each Product must have at least one Product Variant, which is called the Master Variant. For the limits that apply to Products, see Limits.

To support editorial workflows, each Product resource contains the following two representations of its Product data:

  • Current: the published version that you need to present to your Customers on the storefront.
  • Staged: the draft version to which your content editors can make updates, but it remains invisible to your Customers until explicitly published.

It isn't possible to stage certain Product data that's not intended to be exposed in the storefront, such as Tax Category or Price mode. These are immediately made available in the current representation after making any updates.

The Product lifecycle typically follows these steps:

  1. Creation: when a Product is created, both the current and staged representations are identical.
  2. Editing: when a content editor makes changes to the Product, they are applied to only the staged representation. The current representation remains unchanged and is visible to Customers.
  3. Publishing: when the editor is satisfied with the changes, they can publish the Product. This action copies the staged representation to the current representation and marks the Product as published.
  4. Further edits: after publishing, the editor can continue making changes to the staged representation, repeating the cycle.
  5. Unpublishing: if you don't want the Product to appear in the storefront, you can unpublish it. This action keeps the staged and current representations as they are, but it marks the Product as unpublished.
  6. Deletion: when a Product is no longer needed, you can delete it. This action removes both the current and staged representations from the Project. Only unpublished Products can be deleted.
This staging and current mechanism also lets you run a preview site and a production storefront from a single Project. For how to check whether a Product has unpublished edits with the API, see Product catalog APIs overview.
A Product becomes available in a Store only after it's explicitly included in a Product Selection assigned to that Store. This ensures that only the required assortment is visible to Customers in a specific sales Channel.
An individual Product has exactly one Product Type from which it gets its Attributes. The Product Type must exist at the time the Product is created. It can't be changed later.

Slug

A slug is a human-readable identifier used in storefronts as a deep-link URL to the related Product. For example, /products/classic-leather-jacket instead of /products/a1b2c3d4. Slugs must be unique across the Project.

Product Variant

A Product Variant represents a single sellable product, often an individual SKU, and contains the following unique data:
  • Master Variant: every Product has one Master Variant. It ensures that even a simple Product always has at least one variant that can be purchased. It is typically presented as the default on Product detail pages. For how to identify and change the Master Variant with the API, see Product catalog APIs overview.
  • Other variants: an array of additional variants.
  • Variant data: contains the following information that changes for every variant:
    • Prices: specific Prices, including tiers, Customer Groups, and Channels.
    • Images: images that are specific to a color and size combination.
    • Attributes: values for Variant Attributes such as color: Red or size: L.
    • SKU: unique identifier of each variant. The primary role of SKUs is to act as the permanent, machine-readable key for Inventory tracking, ordering, and fulfillment.

      We recommend that you don't frequently change any SKU. Doing so can trigger unwanted performance-impacting changes in related resources like Product Selections.

For the two ways to model Product Variants, see Variants overview.
For how to set an Attribute on all Product Variants with the API, see Product catalog APIs overview.
A Product and its variants can have a one-to-one relationship (for unique Products without variations) or a one-to-many relationship (for Products with different sizes, colors, or materials). For how the number of Product Variants affects API response size, see Products.

Attribute

An Attribute is a specific piece of data that describes a characteristic or property of a Product or Product Variant. Attributes are defined as part of a Product Type. They can be either Product Attributes (common to all variants) or Variant Attributes (specific to each variant).
Attribute constraints control how Attribute values behave across Product Variants:
  • Same for all: ensures consistency across all Product Variants, as the value is maintained at the Product level.
  • Combination unique: guarantees no two Product Variants share the same combination of specified Attributes. Use this constraint for variant dimensions such as color and size.
  • Unique: ensures Attribute values remain distinct within the same Product.
Because the Product Type applies to the entire Product, all variants share the same Attribute schema. If your variants require different Attribute sets, consider using polymorphism patterns. For example, you can use an enum Attribute to differentiate variant types and define optional Attributes specific to each type.

Product Projection

A Product Projection is a specialized representation of a Product that displays data for a specific view. Its main purpose is to represent a Product in the way you want to present to a Customer on your storefront. For how a Product Projection differs from a Product in the API, see Product catalog APIs overview.
In addition, you can tailor Product Projections to fit a specific context, such as a particular Store or sales Channel. The data returned in a Product Projection can be customized based on factors like localization (language), pricing (currency and Customer Group), and Inventory availability.

The two most important aspects of a Product Projection are as follows:

  • Publishing state: choose between current data and staged data. For how the publishing state works with the API, see Product catalog APIs overview.
  • Contextual data: you can "project" the data to fit a specific context. For example, you can query a Product Projection to show the following contextual data:
    • Offered Price for a Product Variant by using the price selection process.
    • Localized Attributes (like name and description) in a specific language, such as German.
    • Inventory availability for a specific warehouse or sales Channel.

    Projecting Prices keeps only the Prices that are relevant to a context, such as a country, Customer Group, or distribution Channel. Your storefront then doesn't need to sort through the full, often long, price list of a Product.

Attribute Group

Attribute Groups help define a logical grouping for Attributes across multiple Product Types and provide fine-grained access control over Product data. You can use Attribute Groups to define and assign specific sets of Product Attributes and Variant Attributes. This helps ensure that only authorized teams can edit those particular values in the Merchant Center.

An Attribute Group lets you group related Attributes for easier data entry and define granular editing permissions. For example, you can bundle color, material, and fit into a Core Specifications group.

The primary purpose of Attribute Groups is to improve the management of Products through access management and user interface organization. For example, you can bundle related Attributes (like meta_title and meta_description into an SEO Metadata group). You can then restrict editing permissions to specific teams (such as the Marketing team).

Depending on the use case, you can grant editing permission to all Attributes, only Attributes within selected Attribute groups, or none. Only teams with editing permissions can edit Attributes.

If multiple Product Types define an Attribute with the same name, teams with access to that Attribute can edit Attribute values for Products of any of those Product Types.

Attributes can be shared among several Attribute Groups for easier management.

Product Type

Product Types help define the Attributes of a Product. You can define the meta-information associated with an Attribute as part of a Product Type. For example, you can configure whether the Attribute is searchable and define its constraints. For the API that manages Product Types, see Product catalog APIs overview.

The primary purpose of Product Types is as follows:

  • Define custom Attributes: configure the set of custom fields (Attributes) that a Product or its variants can have.
  • Configure Attribute structure: define where the values of Attribute are stored:
    • Variant Attribute: Attributes that vary per SKU (like color or size).
    • Product Attribute: Attributes that are identical across all variants (like brand or washing_instructions).
  • Control Attribute behavior: specify the constraints and search behavior for each Attribute:
    • Constraints: enforce rules such as requiring an Attribute or making its value unique across variants.
    • Searchability: specify which Attributes should be searchable, filterable, or used for facets in search queries, which is important for the storefront experience.

When designing Product Types, Products within the same type should share a significant overlap in their Attributes, typically around 80% or above. If Products within the same type don't share many Attributes, many fields remain empty or not applicable. This makes data management more difficult.

Aim to strike a balance between the following approaches:

  • Specific Product Types: fewer Attributes, more relevant to each Product. Too many granular Product Types can complicate maintenance and integration.
  • Generic Product Types: encompass a wide range of Products with many Attributes, but often result in unused fields for each Product.

The choice between specific and generic Product Types depends on where Product data is managed:

  • When managing data in the Merchant Center: use multiple specific Product Types. Using specific Product Types ensures only relevant Attributes are displayed in the Merchant Center.
  • When managing data externally: generic Product Types are more efficient to reduce the number of types and Attributes to synchronize.
For structured or tabular data, learn more about the AttributeNestedType which lets you compose advanced Product Types from reusable building blocks.

Product Selection

You can use Product Selections to manage individual assortments for different sales Channels. For example, if you like to run multiple brand sites, sell your Products in different countries, or operate a network of brick-and-mortar Stores. This feature is useful when you need to segment your Product catalog into assortments for each sales Channel.

A Product Selection is a resource that establishes a relationship between a Store and its Products. It determines which Products are available within the scope of a given Store.

You can create a Product Selection, and then assign specific Products to it. For how a storefront retrieves the Products of a Product Selection with the API, see Product Selections.
We recommend that you use Product Selections to configure backend business logic. For example, you can define the list of Products for a promotion or control the exact assortment available in a Store. Use Categories to configure the frontend navigation and Product browsing experience on your storefront.

You can use a Product Selection in the following key scenarios:

  • Assortment control: allow different geographic regions or distinct brands operating within the same commercetools Project to display only their relevant Products.
  • Product visibility: temporarily limit or expand the catalog for specific sales Channels without modifying Product content.

Two modes of Product Selections are available for specifying a subset of your Project's product catalog. In both modes, you specify each Product individually, but you either include the Products or exclude them explicitly, whichever is more convenient for you.

  • Individual: each Product that should be part of the Product Selection is added explicitly.
  • IndividualExclusion: each Product that should not be part of the Product Selection is excluded explicitly.
Product Selections allow you to control the availability of a Product assortment by activating or deactivating the respective Product Selection for a specific Store.

Our recommended workflow when using Product Selections is the following:

  1. create initial set of Products with their Variants.
  2. create Product Selections.
  3. assign Products and optionally Product Variants to the Product Selections.
After you have created a Product Selection and added Products and Variants to it, you can go ahead and assign it to one or several Stores.

In case you have product assortments that are shared among Stores like

assortment overlap

we recommend creating a separate, shared Product Selection for the Products that the Stores have in common:

Separate Product Selection

A Product Selection can be assigned to multiple Stores. A Store's assortment depends on assigned Product Selections and if they are active or inactive for the Store; if a Product Selection is not assigned to a Store, all your Products will be available in the Store.

  • If Product Selections of type Inclusion are assigned to a Store and if all are inactive, the Store's assortment will be empty. If at least one of the assigned Product Selection is active, the Store's assortment will include Products from the active Product Selection.
  • If Product Selections of type Exclusion are assigned to a Store and all are inactive, the Store's assortment will include all Products. If at least one of the assigned Product Selection is active, the Store's assortment will not include Products from the active Product Selection.
  • If Product Selections of type Inclusion and Exclusion are assigned to a Store and all are active, exclusion of Products takes precedence.

Product Tailoring

Product Tailoring lets you manage market-specific Product information for each of your Stores and customize Product content based on brand or region. If you make any Product content changes for one specific Store, Product Tailoring isolates those changes. They don't affect other Stores.

We recommend that you use localized fields when the content differences among your Stores are related to language translation. And use Product Tailoring when the differences pertain to marketing, legal, or region-specific content.

Deleting a Store permanently removes all associated Product Tailoring data.

You can use Product Tailoring in the following key scenarios:

  • Store-specific naming: change the Product name, description, or slug (URL) to use locally appropriate terms.
  • Asset customization: override the set of images or Product assets to feature models or settings that are relevant for a specific local market.

In addition to managing resource access, a Store is a tool for tailoring Product information. By combining Stores and Product Tailoring, you can customize Product details such as names, descriptions, slugs, images, and selected Attributes on a per-Store basis. This lets you present targeted and relevant catalog content for different Customer segments, regions, or brands.

By tailoring product information to different markets, you can increase visibility, customer loyalty, and number of orders.

To control the availability of your Products for specific Stores, we recommend using Product Selections instead.
Product Tailoring is not a replacement for Localization but an additional option when using Stores. It allows you to control the tailoring of your Product information for each locale individually.
To ensure a consistent user experience for your Customers, the API passes the tailored information to all entities involved in the buying process, such as Shopping Lists, Carts, and Orders.
You can create only one Product Tailoring for each combination of a Product and a Store. It is not possible to share a Product Tailoring between Stores. To assign the same tailored values to a given Product in different Stores, you must create a separate Product Tailoring for each Store.
For any product information that you don't tailor, the original product information is used. For how this works with the API, see Product catalog APIs overview. Falling back to the original product information gives you the flexibility to customize only the information that needs to be tailored for your Store, while not repeating the information that is identical to the original product information.

Product Search

For what Product Search is and which features it supports, see Storefront search overview.

Category

Categories represent a specific group or classification within your Product catalog and help you organize Products in the catalog. They can have a parent Category with a hierarchical structure. Unlike Product Types, which define what data a Product can store, Categories define where a Product belongs in the navigational structure.
If you want to define the list of Products for a promotion, then we recommend that you use Product Selections instead of Categories.

Categories have the following key characteristics:

  • Hierarchical structure: Categories are designed to form a tree structure. You can have multiple root-level Categories; such Categories don't have a parent Category. And each Category can have zero to several child Categories.
  • Product assignment: Products are explicitly linked to one or more Categories. This ensures that a single Product can appear in multiple locations in the storefront navigation simultaneously.

Categories are essential for the following Customer-facing features and content organization:

  • Storefront navigation: Categories form the primary menu structure that Customers use to browse Products on your storefront.
  • SEO optimization: Categories include fields such as slug (the URL part) and meta description that are crucial for search engine optimization (SEO).

When structuring your catalog, start by defining a primary Category tree (typically for navigation), then construct additional Category trees as needed (for example, for promotions).

Products can belong to multiple Categories, and there can be different Category hierarchies for various purposes and Channels. Categories are embedded in the Product search, enabling you to filter and search for Products by their respective parent and child Categories. You can create Categories and customize existing ones based on your specific content, workflows, and metadata requirements.

Assigning Categories to Stores only controls Category visibility in Stores. It does not change discount or search behavior that is based on a Product's own categories.

Categories include built-in fields for search engine optimization, such as unique and internationalizable URL slugs.

Review

A Review is a centralized record of a Customer's feedback. Each Review is typically linked to a specific entity, usually a Product. For the API that manages Reviews, see Product catalog APIs overview.

Reviews have the following key characteristics:

  • Customer feedback collection: Reviews store the rating score, text of the Customer's comment, author's details, and metadata such as the date and title of the Review.
  • Product enrichment: the Reviews API provides aggregated statistics, such as average rating and total count. These statistics are calculated from all linked reviews and displayed as ratings badges on Product pages.
  • Moderation and visibility: Reviews include a State field such as approved, pending, or rejected. This lets you moderate content before it becomes visible on the storefront. Review States are user-defined and configured in a State machine, letting you control the names and allowed transitions.

Product data management

This section describes how to manage your product data to make them available for purchase.

Evaluate requirements

Before modeling your Product catalog, clarify the necessary commerce integrations and their requirements. Pay close attention to any systems that produce or enrich Product information, as they may impose constraints such as required fields or text-length restrictions.

Evaluate additional requirements that can influence the data model, including search functionality, promotions, and pricing. For example, promotions may require specific Attributes to define Product Discounts accurately.

The system where Product information is maintained has a significant impact on the data model.

  • If you manage Products in the Merchant Center, build a model that allows for easy Product edits and supports robust data governance. Set up Attributes as enums or booleans, or group Attributes for intuitive UI navigation.
  • If Product details are managed externally (for example, in a PIM system), you can simplify the model and focus on the primary commerce requirements.

As a general guideline, only include data essential for commerce operations, though exceptions exist when additional Product data benefits downstream integrations.

Collect data

We assume that you have stored basic Product information in your ERP or PIM systems. This includes names, SKUs, technical specifications, supplier details, and compliance data. For more information about integrations that might be available for your PIM system, see our marketplace. If no integration is available, you can find in this section how you can import this data to create a sellable Product catalog.

Standardize and cleanse the data

Before importing Product data, it's essential that you standardize and cleanse the data to ensure consistency and accuracy across your Product catalog. This process can include the following steps:

  • Removing duplicate entries
  • Correcting errors
  • Supplementing missing information
  • Formatting the data into a consistent, standardized structure
Data integrity in your Product catalog is supported in several ways, including uniqueness checks for SKUs and verification of required Attribute values. The commercetools Product model enforces consistent data formats for Attributes by using specific Attribute types (like String, Number, Enum, LocalizedString) defined on Product Types.

Import the data

Several flexible options are available for importing data to suit the following business needs, from manual updates to large-scale automated synchronization:

Merchant Center manual entry

Users can create and edit individual Products and variants directly within the Merchant Center UI. This method is ideal for making small, ad-hoc updates and managing unique Product details one by one.

Merchant Center file upload

For bulk operations, the Merchant Center allows non-technical users to import data by using either CSV or JSON files. This is suitable for initial data migration or periodic mass updates of Products, Prices, and Inventory without needing API development.

Synchronous Products API

You can use the Products API for real-time, synchronous data management tasks, such as create, read, update, and delete operations. This process is ideal for customized Product management applications.

Asynchronous Import API

This dedicated API is designed for high-speed, large-volume data ingestion. It handles data asynchronously, letting you send bulk data (up to 20 resources per request) and continue other tasks. The import is processed in the background. It automatically manages resource dependencies and is the preferred method for large data migrations.

Libraries and CLI tools

You can use tools like commercetools-project-sync from the command-line to synchronize data between different commercetools Projects (for example, from staging to production). commercetools sync is a Java library that lets you import deltas between the data from any arbitrary source to a commercetools Project.

Enrich the Product data

Add detailed content to raw Product data, including marketing descriptions, high-quality images, videos, feature highlights, and Customer reviews. SEO optimization improves Product appeal and search visibility.

Categorize and structure your Products

Organize your Products into logical hierarchies, Categories, and taxonomies to facilitate easy navigation and provide an intuitive Customer experience.

Manage Attributes and variants

Define and manage specific Product attributes (size, color, weight, material) and handle Product variations or configurable bundles and kits.

For a guide on modeling static product bundles, see Manage static product bundles.

Manage pricing and Inventory

Maintain accurate base pricing, promotional offers, real-time Inventory levels, and availability statuses, often by integrating with ERP or inventory management systems.

Each Product Variant must be priced to be added to a Cart. You can store Prices in two ways: Embedded Prices and Standalone Prices.
The Inventory API enables tracking of stock quantities for each Product Variant and supply Channel. For modeling guidance, see the Inventory modeling module.

Manage workflow and governance

Establish clear workflows, role-based access controls, and approval processes to maintain data quality, track changes, and ensure compliance before information is published. For how to enforce validation and replicate catalog configuration with the APIs, see Product catalog APIs overview.

Implement localization and personalization

Customize Product information, including translations, regional pricing, and specific content, for different markets and Customer segments.

Channel distribution and syndication

Publish and synchronize the finalized, enriched Product data across various sales Channels, such as commerce websites, mobile apps, marketplaces (Amazon, eBay), and even print catalogs.

B2B implementations B2B

For B2B implementations, the Stores API with supply and distribution Channels is often used in conjunction with Business Units to define Customer-specific Products and Prices. Although these APIs are pivotal for B2B, they seldom influence Product modeling directly.

Performance monitoring and analysis

Track catalog performance metrics, such as data completeness, conversion rates, and return rates, and use Customer feedback and analytics to inform future optimizations. For how to work with the Product catalog through the APIs, see Product catalog APIs overview.