Migrate to Modular Catalog

Learn how to migrate an existing Project from the Classic catalog model to the Modular catalog model.

The productCatalogModel setting of a Project determines how Product Variants are stored:

Classic: Variants are embedded within the Product. A Product can have up to 100 Product Variants.
Modular: Variants are standalone Variant resources linked to a Product. A Product can have up to 10 000 Variants, each with its own lifecycle. Pricing is handled exclusively through Standalone Prices.

How the migration works

Moving from Classic to Modular means changing two things:

Your data: your Variants must be written as standalone Variant resources, not only as embedded data inside your Products.
Your integration: your code must create, update, and read Variants through the Variant APIs.

If both changed at the same time, you would need a single cutover in which your storefront, your PIM, your ERP, your import pipelines, and every other integration all switched together. The migration path exists so that you can change them one at a time, and reverse any step until the very end. This is made possible by the per-request override and the InMigration state.

For a new Project without existing embedded Variants, see Model and sell products with Modular Catalog.

Per-request override

Per-request overrides let you test Modular resolution without changing the Project setting. Use a header to control which catalog model each request uses. Removing the override restores the Project default. Use it to validate your integration against Modular resolution before completing the migration. See Roll out Modular reads for supported headers and examples.

The InMigration state

A header only affects requests sent by your code. It cannot reach commercetools background processes, the Merchant Center, or third-party integrations that you do not control. Those switch only when the Project's default switches. The InMigration state changes that default to Modular for everything, while keeping the Classic path open:

Variants resolve from standalone Variants by default, with no header needed. This affects resources that reference a Variant, including Cart and Order Line Items, discount matching, and Product Selections.
The Products API and Product Projections API continue to return embedded Variant data, so integrations that read them keep working.
Product Search continues to index embedded Variants by default. However, it can be configured to index products using only standalone Variants in a dedicated search index copy.
Variant update actions on the Product API are still accepted, so dual-write continues to work.

This lets you migrate reads and writes on different schedules. Systems that write catalog data can keep their existing write path and add the standalone Variant write alongside it.

In the InMigration state, a Variant written only as embedded data is not visible to Carts, Orders, or discount matching. Every Variant write must reach both representations for as long as your Project is in this state.
Throughout the migration, Product Search continues to index embedded Variant data.

What each stage provides

Stage	Default resolution	Embedded reads	Embedded Variant writes	Reversible
`Classic`	`Classic`	Yes	Yes	No
`Classic` with header	`Modular` for selected requests	Yes	Yes	Yes, remove the header
`InMigration`	`Modular`	Yes	Yes	Yes, set `Classic`
`Modular`	`Modular`	Yes	No	Yes, set `InMigration`; resynchronize embedded Variants before setting `Classic`
After cleanup	`Modular`	No	No	No

Embedded Variant data is preserved until the cleanup job runs. Cleanup is the point of no return. After cleanup, returning to Classic requires a separate reverse migration, which is not supported.

The Classic catalog model limit

While you are dual-writing, every Variant you create must also be created as an embedded Variant. Embedded Variants remain subject to the Classic limit of 100 Product Variants per Product.

The Modular limit of 10 000 Variants per Product becomes available once you stop writing embedded Variants.

Migrate in stages

To complete the migration successfully, follow these stages:

Meet all the prerequisites.
Start dual-writing Variants.
Request the Variant copy job and Product Search support for InMigration mode.
Roll out Modular reads.
Change Product Catalog Model to InMigration.
Stop writing Variant updates through the Product API.
Change Product Catalog Model to Modular.
Request the cleanup job.

Prerequisites

Before you begin, your Project must meet the following conditions.

All Products use Standalone Prices

The Modular model does not support Embedded Prices. Migrate your prices from Embedded to Standalone Prices before you begin this migration.

To find Products that still have Embedded Prices set, query the prices field on masterVariant and variants, for example, masterData.current.masterVariant.prices on /products, or masterVariant.prices on /product-projections. The following example fetches matching Product IDs with limit=500. If your catalog has more results than that, paginate through using the offset field to find them all.

curl --get "https://api.{region}.commercetools.com/{projectKey}/products" \
  --data-urlencode 'where=masterData(current(masterVariant(prices is not empty))) or masterData(current(variants(prices is not empty))) or masterData(staged(masterVariant(prices is not empty))) or masterData(staged(variants(prices is not empty)))' \
  --data-urlencode 'limit=500' \
  -H "Authorization: Bearer {access_token}" \
  | jq -r '.results[] | .id'

If the query returns Product IDs, set their price mode after migrating their prices:

curl -X POST "https://api.{region}.commercetools.com/{projectKey}/products/{id}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "version": {version_number},
    "actions": [
      { "action": "setPriceMode", "priceMode": "Standalone" }
    ]
  }'

API Client scopes

manage_products:{projectKey}: to create and update Products and Variants.
manage_project_settings:{projectKey}: to change the catalog model of the Project.
manage_orders:{projectKey}: to create and update Carts and Orders.
view_products:{projectKey}: to query standalone Variants and staged Variant Projections.
view_published_products:{projectKey}: to query Variant Projections.

Test on a non-production Project first

Run the full sequence on a sandbox or staging Project with representative data before migrating your production Project.

Start dual-writing Variants

Dual-writing means applying the same Variant changes to both the embedded Variant in the Product and its standalone Variant resource. You must write every Variant creation and update to both representations: the Product API for embedded Variants and the Variants API for standalone Variants.

The copy job copies only the initial Variant data. You are responsible for keeping the embedded and standalone representations in sync throughout the migration. Apply every Variant operation, including create, update, and delete, to both representations.

curl -X POST "https://api.{region}.commercetools.com/{projectKey}/products/{product_id}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "version": {version_number},
    "actions": [
      { "action": "addVariant", "key": "outdoor-jacket-red-m", "sku": "JACKET-RED-M" }
    ]
  }'

curl -X POST "https://api.{region}.commercetools.com/{projectKey}/variants" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "product": { "typeId": "product", "id": "{product_id}" },
    "key": "outdoor-jacket-red-m",
    "sku": "JACKET-RED-M"
  }'

Updating a Variant through the Variants API only works once that Variant exists as a standalone Variant. Before the copy job runs, queue updates for embedded-only Variants and replay them after the copy job completes.

Request the Variant copy job and Product Search support for InMigration mode

Contact the commercetools support team to request the Variant copy job. If you use Product Search, request enabling of the InMigration mode in Product Search also. Include the Region, Project key, preferred time window, and confirmation that all Products use Standalone Prices.

The job creates standalone Variants from embedded Variant data for the current and staged representations. It preserves product, variantId, sku, and key, sets masterVariant as the default Variant for the Product, and sets the Product Variant counter to the highest variantId.

The job fails if there is any Embedded Price left on any Variant. It also drops existing standalone Variants before copying, so any Variant that exists only as a standalone Variant is permanently lost. Create Variants in both representations during dual-write.

Only one job runs per Project at a time. When it completes, the commercetools support team shares a consistency report that identifies Products whose embedded and standalone Variant counts differ.

For Product Search, once InMigration mode is enabled, the service starts maintaining two separate copies of your search index: one based on embedded Variants and the other on standalone Variants.

Roll out Modular reads

While your Project is still in Classic mode, force Modular resolution on individual requests with the x-catalog-model header. Implement the header as a feature toggle so you can turn it off immediately if you see a problem.

curl -X POST "https://api.{region}.commercetools.com/{projectKey}/carts/{cart_id}" \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -H "x-catalog-model: Modular" \
  -d '{
    "version": {version_number},
    "actions": [
      { "action": "addLineItem", "sku": "JACKET-RED-M", "quantity": 1 }
    ]
  }'

The line item's Variant is resolved from standalone Variants, and its price is selected from the Standalone Price for that SKU. Send the same request without the header to compare against Classic resolution.

The header is supported on requests for Shopping Lists, Carts, Product Tailoring, and Orders, both through the HTTP API and the GraphQL API. It is not supported for Product Discounts matching, Inventory, Standalone Prices, or Product Selections.

The header applies to the entire HTTP request. A GraphQL document that mixes a Cart query with a Product query resolves everything under one catalog model. You cannot scope it to an individual GraphQL selection.

When adding a line item in the Modular model, specify an sku, or both productId and variantId. A productId alone is not sufficient.

For Product Search you can force the Modular resolution on individual search requests with the x-ab-test-id: modular-catalog header BETA. When the header is omitted, the search index based on embedded Variants is queried instead.

curl -X POST "https://api.{region}.commercetools.com/{projectKey}/products/search" \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -H "x-ab-test-id: modular-catalog" \
  -d '{
    "query": {
      "exact": { "field": "variants.sku", "value": "JACKET-RED-M" }
    }
  }'

The InMigration mode in Product Search must be enabled by the commercetools support team before you can use this header. If not done yet, contact the commercetools support team to request enabling it.

Change Product Catalog Model to InMigration

Once your integration works correctly against Modular reads, Set Product Catalog Model to the intermediate InMigration state:

curl -X POST "https://api.{region}.commercetools.com/{projectKey}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "version": {version_number},
    "actions": [
      {
        "action": "setProductCatalogModel",
        "productCatalogModel": "InMigration"
      }
    ]
  }'

In InMigration, Variants resolve from standalone Variants by default, while the Products API and Product Projections API continue to return embedded Variant data. Variant update actions on the Product API remain accepted, and Product Search continues to index embedded Variants.

Roll back to Classic

In case you encounter issues or need to revert the migration, you can roll back to the Classic model. To roll back, set Product Catalog Model to Classic.

Treat InMigration as a transition window with a defined end date. Dual-write carries maintenance overhead and creates a risk of drift between the two representations.

Stop writing Variant updates through the Product API

Once your reads are fully served from the Modular model and consistency checks are clean, stop the embedded half of your dual-write. From this point, manage Variants only through the Variants API. This also removes the Classic limit of 100 Variants per Product.

Change Product Catalog Model to Modular

Set Product Catalog Model to Modular

curl -X POST "https://api.{region}.commercetools.com/{projectKey}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "version": {version_number},
    "actions": [
      {
        "action": "setProductCatalogModel",
        "productCatalogModel": "Modular"
      }
    ]
  }'

In Modular mode, Variant update actions on the Product API are rejected. Use the Variants API instead.

Embedded Variant data still exists at this point but is no longer maintained. You can return to InMigration directly because it resolves Variants from standalone resources. Before returning to Classic, synchronize all changes made after embedded writes stopped.

Request the cleanup job

The cleanup job permanently removes embedded Variant data. Do not request it until your Project has run on the Modular model in production long enough for you to be confident in the migration.

After a grace period of at least 30 days from when you stop writing embedded Variants, contact the commercetools support team to request the cleanup job. The Project must be in Modular mode.

After cleanup:

The Products API and Product Projections API no longer return embedded Variant data.
The variants array is empty on the current and staged representations.
masterVariant is reset to a bare shape, with no SKU, attributes, or prices.

Your migration is complete. Variant data is managed through the Variants API, read through the Variant Projections and Variant Attributes APIs, and priced through Standalone Prices.

Migrate to Modular Catalog

How the migration works.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Per-request override.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

The InMigration state.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

What each stage provides.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

The Classic catalog model limit.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Migrate in stages.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Prerequisites.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

All Products use Standalone Prices.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

API Client scopes.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Test on a non-production Project first.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Start dual-writing Variants.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Request the Variant copy job and Product Search support for InMigration mode.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Roll out Modular reads.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Change Product Catalog Model to InMigration.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Roll back to Classic.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Stop writing Variant updates through the Product API.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Change Product Catalog Model to Modular.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Request the cleanup job.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}