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.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

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 the parentCategory 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 the parentCategory collection is the default parent only for the catalog specified by catalogId. 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 a catalogSpecific value does not change the existing base value. If no base value is set, Commerce automatically sets the base value as the same value you set for catalogSpecific.
global specifies the default parent category for a product or collection and applies it in every catalog where the item appears. The global scope resets the base scope value and removes all catalog context from the collection or product's default parent.
revertToBase removes the catalogSpecifc scope for the catalog in context for the product or collection and sets its default parent back to the base 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"
      }
  }