Modular Catalog introduces Variants as first-class resources, decoupled from their parent Product, allowing you to use the Variant APIs to independently model, manage, and retrieve Variants. Using the Modular Catalog, Product Variants can now be modeled in two ways:

• Classic model: Product Variants are embedded within the Product with a 100-variant limit.
• Modular model: introduces Variants as first-class resources, allowing you to model, manage, and retrieve Variants independently from their parent Product. This model:
  • Removes the 100-variant limit to enable catalogs with up to 10,000 Variants per Product.
  • Provides granular control, allowing you to publish or unpublish specific Variants instantly without affecting the entire Product.
  • Optimizes performance by retrieving Variant-level data directly, simplifying storefront integrations and reducing large Product payloads.

For more information about this feature, see the following resources:

• Variants API
• Variant Projections API
• Variant Attributes API
• Model and sell products with Modular Catalog

The following changes were introduced for the HTTP API:

• Added new endpoints:
  • Variants: query, create, update, and delete Variants by id or key, plus bulk updates.
  • Variant Projections: query and retrieve read-only Variant data optimized for storefront rendering.
  • Variant Attributes: retrieve requested variant-level Attributes and lightweight availability for all Variants of a Product.
  • Store-scoped endpoints for Variant Projections and Variant Attributes.
• Added productCatalogModel to Project and ProjectSetProductCatalogModelAction.
• Added defaultVariant to ProductData for Projects using the Modular catalog model.
• Updated ProductData and ProductProjection behavior for Modular projects:
  • masterVariant is omitted.
  • variants is empty.
  • Variant data is retrieved through Variants and Variant Projections.
• Added ProductSetDefaultVariantAction.
• Added Variant update actions:
  • VariantSetSkuAction
  • VariantSetKeyAction
  • VariantSetImagesAction
  • VariantAddExternalImageAction
  • VariantRemoveImageAction
  • VariantSetAssetsAction
  • VariantAddAssetAction
  • VariantRemoveAssetAction
  • VariantSetAttributesAction
  • VariantSetAttributeAction
  • VariantRemoveStagedChangesAction
  • VariantPublishAction
  • VariantUnpublishAction
  • VariantSetAssetKeyAction
  • VariantChangeAssetOrderAction
  • VariantChangeAssetNameAction
  • VariantSetAssetDescriptionAction
  • VariantSetAssetTagsAction
  • VariantSetAssetSourcesAction
  • VariantSetAssetCustomTypeAction
  • VariantSetAssetCustomFieldAction
• Added Variant Message types:
  • VariantCreatedMessage
  • VariantDeletedMessage
  • VariantImageAddedMessage
  • VariantImagesSetMessage
  • VariantKeySetMessage
  • VariantPublishedMessage
  • VariantSkuSetMessage
  • VariantStagedChangesRemovedMessage
  • VariantUnpublishedMessage

The following changes were introduced for the GraphQL API:

• [GraphQL API] Added the following types: Variant, VariantData, VariantDraft, VariantDeletionResult, BulkUpdateVariantsInput, BulkUpdateVariantsItemInput, VariantBulkAction, BulkUpdateVariantsResponse, BulkUpdateVariantsItemResult, BulkUpdateVariantsResource, BulkUpdateVariantsItemError, VariantProjection, VariantAttributeSimpleAvailability, VariantAttributeChannelAvailability, VariantAttributeAvailability, VariantAttributeDefinition, VariantAttributeVariant, ProductProjectionVariantAttributes, and SetProjectSettingsProductCatalogModel.
• [GraphQL API] Added the VariantUpdateAction input type with the following actions: setSku, setKey, setImages, setAssets, setAttributes, setAttribute, addExternalImage, removeImage, addAsset, removeAsset, setAssetKey, changeAssetOrder, changeAssetName, setAssetDescription, setAssetTags, setAssetSources, setAssetCustomType, setAssetCustomField, removeStagedChanges, publish, and unpublish.
• [GraphQL API] Added the VersionControl enum with values On and Off.
• [GraphQL API] Added the ProductCatalogModel enum with values Classic and Modular.
• [GraphQL API] Added the variant and variants query fields.
• [GraphQL API] Added the variantProjection and variantProjections query fields (also available under inStore).
• [GraphQL API] Added the productProjectionVariantAttributes query field (also available under inStore).
• [GraphQL API] Added the createVariant, updateVariant, deleteVariant, and bulkUpdateVariants mutation fields.
• [GraphQL API] Added the setProductCatalogModel field to the ProjectSettingsUpdateAction type.
• [GraphQL API] Added the setDefaultVariant field to the ProductUpdateAction type.
• [GraphQL API] Added the defaultVariantRef and defaultVariant fields to the ProductData type.
• [GraphQL API] Added the productCatalogModel field to the ProjectProjection type.
• [GraphQL API] Added the following message types:
  • VariantCreated
  • VariantDeleted
  • VariantPublished
  • VariantUnpublished
  • VariantStagedChangesRemoved
  • VariantImagesSet
  • VariantImageAdded
  • VariantSkuSet
  • VariantKeySet

The following changes were introduced for the Import API:

• [Import API] Added Import Variants endpoint.
• [Import API] Added VariantImportRequest to support Variant import requests.
• [Import API] Added variant to ImportResourceType and as the request discriminator for Variant import requests.
• [Import API] Added an example payload for Variant import requests in Import Requests.