Create default parent collections
A collection or product can be the child of more than one collection, in more than one catalog. Its default parent is the collection that determines its hierarchy in a catalog.
Linking products and collections to multiple catalogs provides a more flexible catalog strategy, but can complicate navigation. This is especially true if a shopper accesses a collection or product through a search engine rather than by traversing the catalog hierarchy.
A product or collection's parentCategory
and parentCategoryScope
properties allow you to specify a default parent collection for each catalog where a product or collection is linked. The value of parentCategory
must be the categoryId
of a collection that is one of the item's existing parents.
The scope of the parent setting, that is, where it should be applied, is specified by its parentCategoryScope
property. You set both properties when you create or update a collection with the createCollection
and updateCollection
endpoints, or when you create or update a product with the createProduct
and updateProduct
endpoints.
The parentCategoryScope
property can have one of the following values:
base
specifies that theparentCategory
collection is the default parent in all catalogs where it is included. Use this scope when you want to specify the default parent collection that should apply wherever the collection or product is shared, unless it is overridden for a specific catalog.catalogSpecific
specifies that theparentCategory
collection is the default parent only for the catalog specified bycatalogId
. Use this scope for a product that should be available only in a specific catalog, for example, a product that can be sold only in a certain country. Setting acatalogSpecific
value does not change the existingbase
value. If nobase
value is set, Commerce automatically sets the base value as the same value you set forcatalogSpecific
.global
specifies the default parent category for a product or collection and applies it in every catalog where the item appears. Theglobal
scope resets thebase
scope value and removes all catalog context from the collection or product's default parent.revertToBase
removes thecatalogSpecifc
scope for the catalog in context for the product or collection and sets its default parent back to thebase
scope.
If no scope is specified in a PUT or POST request, and a catalog-specific value exists, the request uses that value. Otherwise, the request uses the base
value.
Set a default parent for a collection
This section contains Admin API examples that show how to set a default parent for a collection. To update a collection, issue a PUT request to the /ccadmin/v1/collections/{id}
endpoint. To create a collection, issue a POST request to the /ccadmin/v1/collections/{id}
endpoint.
The examples in this section are based on the following scenario:
A Commerce instance includes two sites, one for US shoppers and one for UK shoppers. Each site has
its own catalog, usCatalog
and ukCatalog
, respectively.
The BigBrand collection is linked to the following locations in both catalogs:
- UK-Catalog / StorefrontNav / New / BigBrand
- UK-Catalog / StorefrontNav / Brands / BigBrand
- US-Catalog / StorefrontNav / New / BigBrand
- US-Catalog / StorefrontNav / Tableware / Brands / BigBrand
The following example updates the default parent collection for BigBrand to Brands. This change affects both catalogs, since the Brands collection exists in both.
PUT /ccadmin/v1/collections/bigBrand
{
"properties":{
"parentCategoryScope": "base",
"parentCategory" : "Brands"
}
}
The following example updates the default parent collection for BigBrand to New in the US Catalog only. It does not affect BigBrand's default parent collection in the UK Catalog.
PUT /ccadmin/v1/collections/bigBrand
{
"properties":{
"catalogId": "usCatalog",
"parentCategoryScope": "catalogSpecific",
"parentCategory" : "New"
}
}
The following example updates the default parent collection for BigBrand to Brands. This change affects both the US and UK catalogs, even if a catalog-specific default parent was previously set, as in the previous example.
PUT /ccadmin/v1/collections/bigBrand
{
"properties":{
"parentCategoryScope": "global",
"parentCategory" : "Brands"
}
}
The following example updates the default parent collection for BigBrand to New in the UK Catalog only. It does not affect BigBrand's default parent collection in the US Catalog.
PUT /ccadmin/v1/collections/bigBrand
{
"properties":{
"catalogId": "ukCatalog",
"parentCategoryScope": "catalogSpecific",
"parentCategory" : "New"
}
}
The following example clears the catalog-specific parent setting from the previous example. The default parent collection for BigBrand in the UK Catalog is now set to Brands, which was set as the base
value in the first example in this section. Note that the request includes a catalog context ("catalogId": "ukCatalog"
). A catalog context is required to set the parentCategoryBase
torevertToBase
.
PUT /ccadmin/v1/collections/bigBrand
{
"properties":{
"catalogId": "ukCatalog",
"parentCategoryScope": "revertToBase"
}
}
Set a default parent for a product
This section contains Admin API examples that show how to set a default parent for a product with the /ccadmin/v1/products
endpoints. To update a product, issue a PUT request to the /ccadmin/v1/products/{id}
endpoint. To create a product, issue a POST request to the /ccadmin/v1/products/{id}
endpoint.
The code examples in this section are based on the following scenario:
A Commerce instance includes two sites, one for US shoppers and one for UK shoppers. Each site has
its own catalog, usCatalog
and ukCatalog
, respectively. A
serving platter is linked to the following locations in both catalogs:
- UK-Catalog / StorefrontNav / New / Large Oval Platter
- UK-Catalog / StorefrontNav / Brands / BigBrand / Large Oval Platter
- US-Catalog / StorefrontNav / New / Large Oval Platter
- US-Catalog / StorefrontNav / Tableware / Large Oval Platter
The following example updates the default parent collection for the Large Oval Platter to New. This change affects both catalogs, since the New collection exists in both.
PUT /ccadmin/v1/products/prod_largeOvalPlatter
{
"properties":{
"parentCategoryScope": "base",
"parentCategory" : "New"
}
}