Documentation

Product catalog overview

Overview of the APIs and related concepts for managing the Product catalog of your Composable Commerce Project.

Ask about this Page
Copy for LLM
View as Markdown

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

This central repository lets you support structured data across all Products (Product Types), define navigational pathways (Categories), control Store-specific visibility (Product Selections), and manage how Products are shown to Customers on a storefront (Product Projections).

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

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, typically presented as the default on Product detail pages.
  • 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 because this can trigger unwanted performance-impacting changes in related resources like Product Selections where the SKU is used as an identifier.

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 and can be either Product Attributes (common to all variants) or Variant Attributes (specific to each variant).

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. This means that 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 uses this process to filter Prices based on the provided Store context (currencies, countries, and distribution Channels) to find the most relevant and targeted Price.
    • 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 (such as to bundle color, material, and fit into a Core Specifications group) and define granular editing permissions based on these groups.

The primary purpose of Attribute Groups is to improve the management of Products through access management and user interface organization. For example, they let you bundle related Attributes (like meta_title and meta_description into an SEO Metadata group) so that you can restrict editing permissions to specific teams (such as only for the Marketing team).
For enhanced usability, in the Merchant Center, Attribute Groups replace long Attribute lists with cleaner, collapsible panels labeled by the group name, making 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.

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 for all those scenarios in which the entire Product catalog needs to be segmented into assortments that fit the respective sales Channel.

A Product Selection is essentially a separate resource that establishes a relationship between one Store and many Products that 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, such as defining the list of Products for a promotion or controlling the exact assortment available in a specific Store. And 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 changes to a single Store so that 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.

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

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, that are calculated from all linked reviews, which are then used to display 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 in Composable Commerce to make them available for purchase.

Collect data

We assume that you have stored various basic Product information such as names, SKUs, technical specifications, supplier details, and compliance data in your ERP or PIM systems. 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 into Composable Commerce to create a sellable Product catalog.

Standardize and cleanse the data

Before importing Product data into Composable Commerce, 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
Composable Commerce has several methods to support data integrity in your Product catalog, such as uniqueness checks for SKUs and verifications for 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.

Ingest the data

Composable Commerce offers several flexible options for data ingestion 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 while 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 through the command line to synchronize data between different Composable Commerce 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 Composable Commerce project.

Enrich the Product data

Add detailed and engaging content to raw Product data, including marketing descriptions, high-quality images, videos, feature highlights, Customer reviews, and SEO optimization to improve 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".

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.

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.

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 e-commerce websites, mobile apps, marketplaces (Amazon, eBay), and even print catalogs.

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 that are relevant to a specific context, such as a particular country, Customer Group, or distribution Channel. This practice simplifies client-side logic by preventing API responses from being cluttered with a Product's entire, often extensive, Price list.

Projection by Store

To remove unecessary Embedded Prices from Product Projections, you can filter them based on the Product distribution channels configured in the Store, which is specified 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, which is specified 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 to specify Product Attributes that you want to include or exclude in the Product Projections 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

Composable Commerce offers two primary APIs 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.