Product catalog overview

Ask about this Page
Copy for LLM
View as Markdown

Overview of the APIs and related concepts for managing 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. A Product can have a maximum of 100 Product Variants.

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 sets the published flag as true.
  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 sets the published flag as false.
  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.
You can check the hasStagedChanges and published fields on a Product Projection to determine whether a Product has unpublished edits or is currently published. This staging and current mechanism also lets you run a preview site and a production storefront from a single Project.
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. A Product can contain between 1 and 100 Product Variants. These are the actual sellable units (SKUs) and contain the following unique data:
  • Master Variant: every Product has one Master Variant. The Master Variant always has id set to 1. 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. You can reassign which variant is the Master Variant by using the Change Master Variant update action.
  • 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.

In the Merchant Center, Variant Attributes with the SameForAll constraint are editable as Product-level Attributes. Editing them sets the Attributes on all variants. When updating product data through the HTTP API, you can use the Set Attribute in All Variants update action.

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

Keep in mind that each API response for a Product includes all its Product Variants and Attributes. If a Product has many Product Variants with numerous Attributes, the response size increases, which affects loading and rendering times. For such cases, consider using the GraphQL API.

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:
  • SameForAll: ensures consistency across all Product Variants, as the value is maintained at the Product level.
  • CombinationUnique: 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. Unlike the full Product resource, which contains both current and staged data simultaneously, a ProductProjection restricts the data to just one of these representations. Its main purpose is to represent a Product in the way you want to present to a Customer on your storefront.
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 by using the staged query parameter on the Product Projections endpoints. These endpoints request the current projection by default because it's the typical use case for Customer-facing storefronts.
  • 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 Product price selection process. The Product Projection API filters Prices based on the Store context (currencies, countries, and distribution Channels) to find the best match.
    • Localized Attributes (like name and description) in a specific language, such as German.
    • Inventory availability for a specific warehouse or sales Channel.

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).
In the Merchant Center, Attribute Groups replace long Attribute lists with cleaner, collapsible panels labeled by the group name. This makes data entry much more intuitive.

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.

At the API level, a Product Type is its own resource and is managed through the Product Types endpoint.

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. Your frontend application makes a Product Projections API call to retrieve the Products that are part of the Product Selection.

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.

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.

Searching for Products by using Store-specific tailored names isn't possible in the Merchant Center. Also, you can't import or export Product Tailoring data from the Merchant Center.

Product Search

The Product Search API lets you create storefront discovery experiences for Customers, enabling them to browse and search for Products. It works primarily with Product Projections rather than with the entire, complex Product resource.
Product Search indexes only the current representation of a Product resource, not the staged representation.

You can use the Product Search API to implement the following features on your Product listing page:

  • Full-text search: let Customers find Products by entering specific search terms.
  • Filtering and facets: enable the feature to refine results by using dynamic filters (facets) based on Product Attributes, such as filtering Products by size, color, or brand.
  • Sorting: order search results by various criteria such as Price, popularity, or newest arrivals.

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

Review

A Review is a centralized record of a Customer's feedback. Each Review is typically linked to a specific entity, usually a Product. You can use the Reviews API to manage the Reviews that are associated with various Products.

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

Product modeling elements (such as Product Types, Attributes, and Categories) span multiple Projects including development, staging, and production. Set keys on all entities to ensure that you can replicate the data across different environments. After establishing the foundational structure, consider using an infrastructure-as-code tool to manage Product Types, Attributes, Categories, and more. For example, you can use Terraform with the commercetools Terraform provider.

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.

Storefront consumption

Projection dimensions

Current / staged

At any time, a Product has either one or two projected representations, depending on whether the Product is currently published. Only published Products have a current projected representation. Newly created Products only have a staged projected representation. Typically, a storefront application retrieves the Product data by either querying or searching the current Product Projections.

Locales

To remove unecessary translations from Product Projections, you can filter LocalizedStrings based on locales. The locales that should be included in the Product Projection are determined in the following order:
  • Locales defined directly with the localeProjection query parameter.
  • Locales configured in the Store that's specified with the storeProjection query parameter.
Projecting on locales also affects Line Items of Carts that are bound to a Store.

If no translation is found on a given field for the specified locales, another locale is used as a fallback. This ensures that required fields can't remain empty in the Product Projection.

Prices

Price projection is a mechanism for filtering Prices that are included in a Product Projection. It ensures that the API response for a Product contains only the Prices relevant to a specific context, such as a particular country, Customer Group, or Channel. This simplifies client-side logic by keeping responses concise.

Projection by Store

To remove unecessary Embedded Prices from Product Projections, you can filter them based on the distribution channels configured in the Store. Specify the Store with the storeProjection query parameter.
If the Store has distributionChannels set, then the Product Projection includes only the Prices that meet any one of the following criteria:
  • The Price has a distribution Channel that's included in the Store's distributionChannels.
  • The Price doesn't have an assigned distribution Channel.
Similarly, if the Store has countries set, then the projection includes only the Prices that meet any one of the following criteria:
  • The Price has a country that's included in the Store's countries.
  • The Price doesn't have any assigned country.
This filtering logic applies to the prices array within the Product Projection.
Price projection by Store applies only to Embedded Prices. Standalone Prices aren't computed by using Store Channels or countries. To retrieve a Standalone Price in Product Projections, apply projection by Price selection.

Projection by price selection

Price selection lets you to select one price for your Product that's the best matching Price for a Customer. This best match can be either an Embedded Price of the Product Variant or a Standalone Price associated with the Product Variant. The platform selects the best matching price based on the Price selection parameters, such as priceCurrency, priceCountry, priceCustomerGroup, and priceChannel.

When Price selection is applied, the Product Variants that are returned contain the following two fields with Prices:

  • The prices array contains Embedded Prices (optionally projected by Store); Standalone Prices are never included.
  • The optional price field contains the best matching Price based on the provided Price selection parameters. This can be either an Embedded Price or a Standalone Price.

Inventory entries

To remove unecessary Product Variant Availabilities from Product Projections, you can filter them based on the Inventory supply Channels configured in the Store. Specify the Store with the storeProjection query parameter.
If the Store has supplyChannels set, then only the following Inventory entries are included in the projected Product Variants availability:
  • Inventory entries with a supply Channel that's included in the Store's supplyChannels
  • Inventory entries without a supply Channel
Projecting on Inventory entries also affects the Line Items of Carts that are bound to a Store.

Product Selection assignments

To retrieve only those Product Projections that are assigned to a particular Product Selection, use the Get ProductProjection in Store endpoints. For Product Selections that have only specific Product Variants assigned, these endpoints return only those Variants in the retrieved Product Projections.

Attributes

To reduce the response size and improve performance, use the filter[attributes] query parameter. It lets you specify which Product Attributes to include or exclude in the response.
  • Include Attributes: specify the Attribute names to include them in the response.
  • Exclude Attributes: add a dash (-) before the Attribute names to exclude them from the response.

You can include or exclude Product Attributes, Attributes in the Master Variant, and all other variants of the Product.

Here are a few example queries:

Include only specific Attributesbash
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/{id}?filter[attributes]=color&filter[attributes]=size -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
This returns only the color and size Attributes in the Product Projections response.
Exclude specific Attributesbash
curl --get https://api.{region}.commercetools.com/{projectKey}/product-projections/{id}?filter[attributes]=-description&filter[attributes]=-specifications -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
This returns all Attributes except description and specifications in the Product Projections response.

Product Projections API vs. Product Search API

Two primary APIs are available for Product discovery and retrieving Product information: the Product Projection API and the Product Search API. Both read-only APIs are optimized for Customer-facing storefront needs, but they serve different use cases and have distinct characteristics.

The following table compares use cases and features of each API, and it provides performance tips for optimal usage:

FeatureProduct Projections APIProduct Search API
Purpose
  • Retrieves projected representations of Products by their Key or ID or by using Query Predicates.
  • Provides advanced storefront Product discovery at scale, especially across many Stores, Product Selections, and Standalone Prices.
Use case
  • Use in scenarios where tailored and contextualized product data is needed, such as on the Product details page (PDP).
  • Use for full-text and prefix search, filters, and facetted navigation on Product listing pages (PLPs).
Data consistency
Query language
  • Simple filtering by using Query Predicates.
  • Only exact match on standard and Attribute values.
  • Complex filters with expressive search query language, supporting full-text, prefix, and wildcard queries.
  • Calculates facets.
Data returned
  • Product Projections tailored to the requested context.
  • IDs of matching Products and the IDs and SKUs of matching Product Variants.
  • Facets
Publishing state
  • Retrieves published Product data by default, but supports retrieval of staged data by query parameter.
  • Can retrieve tailored as well as original Product data.
  • Indexes the current representation of published Products with their Standalone Prices.
  • Doesn't index tailored Product data.
Product Selections
  • Supports retrieval of only those Products that are assigned to a particular Product Selection.
  • Supports filtering by Stores and Product Selections.
Performance tips
  • Use this API only for a small number of lookups by ID or Key or for simple queries.
  • Cache retrieved Product data.
  • Avoid inefficient query patterns.
  • Fetch the full Product data for the returned Product IDs from an application-side cache or a secondary API call (GraphQL or Get Product Projection by ID).
  • Apply search query optimization techniques.