1. Using Oracle Commerce
  2. Manage Your Catalog
  3. Work with filtered catalogs

Work with filtered catalogs

A filtered catalog provides a filtered view of an existing independent catalog.

Filtered catalogs let merchants scale to a larger number of catalogs with less work and provide flexibility for merchants who sell to a number of accounts or in a number of countries. Filtered catalogs provide central management of collections and taxonomies and give merchants fine-grained control of account-level availability of products.

While independent catalogs can contain different collections and products, a filtered catalog references only products and collections that are already in its base independent catalog; you can, however, show or hide selected products from within the filtered view.

You must create the first new filtered catalog in your Commerce instance with the Admin API or via import. Once you have created the initial catalog, you can work with filtered catalogs on the Catalog page in the administration interface.

You can assign filtered catalogs to sites or, if your store supports account-based commerce, to business accounts. You assign filtered catalogs in the same way you assign independent catalogs. See Associate catalogs with sites or accounts for details.

Understand the benefits of filtered catalogs

Because filtered catalogs let merchants scale to a larger number of catalogs and reduce manual duplication of effort, they are useful for merchants who share catalog taxonomies (collection hierarchies) across catalogs but want to have unique product membership per account or site.

This section describes two cases where a merchant would benefit from using filtered catalogs.

  • An account-based merchant has one large main catalog that contains all the products the merchant sells.

    The merchant sells to a large number of accounts and assigns the full main catalog to about two-thirds of them. Each of the remaining accounts requires a catalog that contains a subset of the products from the main catalog.

    The merchant can set up a filtered view of the main catalog for each remaining account. Each filtered view has the same taxonomy as the main catalog, but contains only the products that are appropriate for the account to which it is assigned. For example, 70% of the products from the main catalog can be marked as core products that are available in all the filtered views. The remaining products can be tagged as needed on a per-view basis.

  • A merchant has two main catalogs, one for sales in Europe and one for sales in North America. They have country store sites for Spain, Germany, UK, France, Italy, the US, Canada, and Mexico.

    To avoid the need to recreate the hierarchy for each country catalog, the merchant creates a filter view catalog based on the European catalog for each of the following country stores: Spain, Germany, UK, France, and Italy.

    Similarly, the merchant creates filtered catalogs based on the North American catalog for Canada and Mexico. (The US store uses the full North Amercann catalog.)

    The entire Wellness collection is not available in Spain, so a business user can hide all products from this collection in the filtered view for the Spanish site. After she publishes her changes, the Wellness collection no longer appears in the menu for the Spanish site. Three products in the Nail Polish collection are not available for sale in Germany due to ingredients restrictions. The business user can navigate to the Nail Polish Collection in the German filtered view and hide the three products that are not available in Germany. Once she publishes her changes she will see that three nail polishes are no longer showing up in the Nail Polish Collection on the German site.

    Similarly, the entire Footspa collection is not available in Canada, so a business user can hide all products from this collection in the Canadian filtered view of the North American catalog.

Keep in mind that performance can be impacted if each filtered view contains a large number of non-core products. The best approach to filtered views is to have a set of core products and filter out by exception.

Understand the structure of filtered catalogs

There are a number of tasks that you cannot perform in filtered catalogs. You can perform the following tasks only in the independent catalog that the filtered view is based on:

  • Create a new product or collection.
  • Edit or delete an existing product or collection.
  • Rearrange products in a collection or rearrange collection hierarchy.
  • Work with product types, price groups, inventory, and media.

Any changes you make in a base independent catalog are automatically applied to the filtered views that include the items that were changed. Remember that you must publish your changes before they will appear on your stores.

Create a filtered catalog

The administration interface supports creating independent catalogs only. To create filtered catalogs, you must use the Admin API.

Note: You can also create new filtered catalogs by using the CSV import feature. See Import catalog items and inventory to learn how to create filtered catalogs by importing.

To create a catalog, you can use the createCatalog endpoint in the Admin API. The catalogVersion and baseCatalog properties specify that you are creating a filtered catalog:

  • Set the value of catalogVersion to 3 to specify that the createCatalog endpoint should create a filtered catalog.
  • The value of baseCatalog must be the catalog ID of an existing independent (version 2) catalog. Otherwise, the request returns an error.

The createCatalog request cannot associate collections with the new filtered catalog. If the request includes categoryIds, an error is returned.

The following example uses the createCatalog endpoint to create a filtered catalog: 

POST /ccadmin/v1/catalogs  HTTP/1.1
Content-Type: application/json
x-ccasset-language: en

{
  "catalogVersion": 3,
  "catalogId": "catSpain",
  "displayName": "Spain",
  "baseCatalog": "catEuro"
}

The response returns the properties of the catalog:

{
  "catalogVersion": 3,
  "defaultCategoryForProducts": null,
  "baseCatalog": {
    "catalogVersion": 2,
    "defaultCategoryForProducts": {
      "repositoryId": "cat40013"
    },
    "rootNavigationCategory": {
      "repositoryId": "rootCategory"
    },
    "displayName": "European Main Catalog",
    "repositoryId": "catEuro",
    "rootCategories": [
      {
        "repositoryId": "nonNavigableCategory"
      },
      {
        "repositoryId": "rootCategory"
      }
    ],
    "id": "catEuro"
  },
  "displayName": "Spain",
  "repositoryId": "catSpain",
  "rootCategories": [],
  "links": [
    {
      "rel": "self",
      "href": "http://myserver.example.com:9080/ccadmin/v1/catalogs"
    }
  ],
  "id": "catSpain"
}

After creating a catalog, you must publish your changes to make it available to use on your sites. See Publish Changes for more information.

Understand product membership in filtered catalogs

The updateProductMembership endpoint enables and disables membership of products to linked filtered catalogs. Use this endpoint to perform the following tasks:

  • Specify products as core products, which will automatically become members of all linked filtered catalogs unless explicitly excluded. Whenever a new filtered catalog is created, it will automatically contain all its base catalog's core products.
  • Exclude core products from specific filtered catalogs.
  • Include products that are not core products in specific filtered catalogs.

The updateProductMembership endpoint's properties specify how products are assigned to filtered catalogs.

  • catalogId is an optional property that specifies a catalog context for the request. Only filtered catalogs that are linked to the specified can be updated by the request.
  • coreProduct is a Boolean that specifies whether products are core products. If the value of this property is null, the existing core-product status of the products will not change.
  • filteredCatalogs is a list of filtered catalog IDs that will include or exclude the products, depending on the products' coreProduct values.
  • enableMembership is a Boolean that adds or removes products to the catalogs specified by filteredCatalogs. If the request does not include the catalogId property, then the catalogs specified by this property will explicitly replace existing values and will be treated as inclusive or exclusive depending on whether a product is a core product. If the request does include the catalogId property, then only the filtered catalogs linked to that catalog are replaced. Other filtered catalogs that contain the product remain unchanged.

The following sample adds camera_1 and camcorder_1 to the filtered catalogs myFilteredView1 and myFilteredView3. These products are not core products. 

POST /ccadmin/v1/products/membership  HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
    "filteredCatalogs":[
        "myFilteredView1",
        "myFilteredView3"
    ],
    "enableMembership":true,
    "products":[
        "camera_1",
        "camcorder_1"
    ],
    "coreProduct":false
}