Export and import catalog data
Catalog data describes the structure of a catalog and specifies the catalog type (independent, filtered, or legacy).
By default, Commerce includes a single catalog called Product Catalog. However, merchants can create and assign additional catalogs. Commerce supports the following types of catalogs:
- Independent catalogs (version 2) are not dependent on any other catalog in your environment. The default Product Catalog is an independent catalog.
- Filtered catalogs (version 3) provide custom views into the Product Catalog.
- Legacy catalogs (version 1) are an older type of secondary catalogs that provide custom views into the Product Catalog.
For detailed information about the different types of catalogs see Understand catalogs.
During an import, the supportVersion1Catalogs
attribute determines which type of catalog to use. If this attribute is set to false
, and a catalog version is not provided, an independent catalog will be created. If the supportVersion1Catalogs
attribute is set to true
, then you can create both an independent and legacy catalog. If you set the catalogVersion
property value to 1, a legacy catalog is created. If you set the catalogVersion
property value to 2, an independent catalog is created. Note that the catalogVersion
attribute is added to export data, and cannot be updated.
The fixedParentCategories
, ancestorCategories
, parentCategoriesForCatalog
and computedCatalogs
attributes are updated in the repository for each child category that is linked or to be unlinked from a catalog, including any of its child categories.
Top level root categories (both navigation and non-navigation) are made when creating a catalog and cannot be moved or deleted from the catalog. Root categories, however, are not made when creating a legacy catalog. The default Product Catalog cannot be deleted but it may be updated and exported.
The following is a sample request for a catalog import:
{
"displayName": "Classical Movies Catalog",
"rootCategories": [
{
"id": "category_1"
},
{
"id": "category_2"
}
],
"id": "ClassicalMoviesCatalog"
}
The catalogVersion
, rootNavigationCategory
and defaultCategoryforProducts
attributes are exported. You can export all catalogs, including the default master catalog, in the repository along with rootCategories
. The rootCategories
attribute in the response contains navigation and non-navigation categories for standard catalogs, and any number of categories for Master View catalogs, and cannot be updated. The fixedChildCategories
for navigation and non-navigation categories are exported for all catalogs, except for Master View catalogs.
The following is an example of a response:
{
"catalogVersion": 2,
"defaultCategoryForProducts": {
"id": "category_1"
},
"rootNavigationCategory": {
"id": "rootCategory_1"
},
"displayName": "Classical Movies Catalog",
"rootCategories": [
{
"fixedChildCategories": [],
"id": "nonNavigableCategory_1"
},
{
"fixedChildCategories": [
{
"id": "cat40013"
},
{
"id": "cat60023"
}
],
"id": "rootCategory_1"
}
],
"id": "ClassicalMoviesCatalog"
}
The following section describes the fields and validation that occurs when exporting or importing catalog data.
Catalog export and import fields
The following fields can be exported and imported for catalogs.
Field Name | Description |
---|---|
displayName |
The name of the catalog. |
Id |
The ID of the catalog. |
rootCategories |
An array of categories associated with the catalog. From this field, you can
export the Id fields of the categories.
|
translations |
This field indicates the different names for an attributed based on the language. The current
|
catalogVersion |
Specifies the type of catalog. 1 specifies a legacy catalog, 2 specifies an independent catalog, and 3 specifies a filtered catalog. |
defaultCategoryForProducts |
Identifies the default collection for a product. By default this links the product to the default collection in a site's default catalog. If this attribute is null, the product is orphaned. |
rootNavigationCategory |
Identifies the navigation category for a catalog. |
When there is a relationship between entities such as a collection and products, relationship updates are Full updates. New relationships override existing ones during the import or export process.
During import, you can link independent collections to catalogs. When you create a
Master View catalog, the top level root categories are not created. By default, the master
catalog’s navigation category is linked to the rootNavigationCategory
attribute. Additionally, you can link any of the Master View catalogs to collections that
are only available in the default master catalog. Errors will occur if you try to link a
collection that is not in the master catalog.
When you create a catalog, the top level root categories are created; this is not the case with Master View Catalogs.
Catalog validations
The following validations are performed when importing catalogs:
- The required
displayName
is valid. - The required
catalogId
is valid and must contain only alphanumeric, underscore (_) or dash (-) characters. - The
rootCategories
array should have valid categories. - The
catalogVersion
attribute value is validated based on thesupportVersion1Catalogs
attribute setting. - The
defaultCategoryForProducts
attribute is validated to ensure that you are not linking a collection to a root category of a standard catalog.
Special handling of large products import
You may experience some performance issues if you import more than 100,000 products and the products are not properly categorized. To avoid import performance issue, please follow these guidelines:
- A collection should not hold too many products. Try to restrict it to 10,000 products per collection
- Avoid creating too many price list groups.
Import Parameter
You should pass the parameter fullPublishMode
as
true
when initiating a large import. Use this option with care since the
recording of the changes are disabled to speed up the import process. Full publish becomes
mandatory after the imports are performed using this parameter. Note that "full publish"
means that all changes will be published.
For example, a sample request payload to trigger initial data import:
{
"mode": "standalone",
"id": "Products",
"format": "json",
"params": {
"fullPublishMode": "true",
"update": "false"
}
}
Note:
fullPublishMode=true
should only be used for initial data imports.
publishChangeLists
publishChangeLists
endpoint can be used to perform to publish all changes:/ccadmin/v1/publishingChangeLists/publish {"operationType":"publish", "skipDependencyCheck":"true"}
You can optionally set skipDependencyCheck:"true"
to skip any other dependency checks from other modifications that are not necessary for publish operations.
Bulk import and export filtered catalogs
You can bulk import and export filtered catalogs. For detailed information on working with filtered catalogs, refer to Configure catalogs with optional collections.