Categories and products can be augmented with content of type CMExternalChannel and CMExternalProduct, respectively. These content objects are created in Studio, if you choose the menu item Augment Category for categories or Augment Product for products. See Section 6.2.3, “Adding CMS Content to Your Shop” in Studio User Manual for more details.

If a product is augmented, an augmenting content is created and the product/category is linked internally via the externalId field. If you query the augmentation for the product/category from the Headless Server, you receive a ProductAugmentation or CategoryAugmentation respectively. An Augmentation type provides access to page grid placements, linked assets or the augmenting content itself. Note that not every product/category is augmented and therefore the content field can be null.

In contrast to plain content related page grid placements, page grids for augmentations are inherited along the commerce navigation hierarchy. For example, a product variant cannot be augmented itself, instead it inherits placements from the parent product, a product inherits placements from its category, which in turn inherits placements from its parent category or channel, all up the commerce navigation hierarchy.

There are two ways to do augmentation queries:

Query for augmenting content with CommerceRoot

To retrieve the hierarchy information of the category tree the Headless Server uses a connection to a commerce adapter under the hood. These augmentation queries can be found below the CommerceRoot (see section Section 7.1, “Headless Commerce Integration Architecture”).

{
      commerce {
    productAugmentationBySite(externalId: "PC_BRITISH_TEA", siteId: "99c8ef576f385bc322564d5694df6fc2") {
      pdpPagegrid {
        placements(names: ["header", "additional"]) {
          ...
        }
      }
    }
  }
}

Query for augmenting content with ContentRoot

In contrast, the Headless Server also offers augmentation queries below the ContentRoot. These queries do not rely on an underlying commerce connection, but need to receive hierarchy parameter from the client. In case the commerce connection is sometimes slow, it can also slow down the augmentation queries of the Headless Server.

{
      content {
    productAugmentationBySite(externalId: "PC_BRITISH_TEA", breadcrumb: ["PC_DELI", "PC_ToDrink"], siteId: "99c8ef576f385bc322564d5694df6fc2") {
      pdpPagegrid {
        placements(names: ["header", "additional"]) {
          ...
        }
      }
    }
  }
}

You might have noticed the difference between the call below content and commerce. The call below content needs an additional breadcrumb parameter, as this query cannot use an underlying Commerce Hub connection to automatically resolve the category hierarchy of the requested product. The breadcrumb information is used to search for augmented categories in the content repository.

An Augmentation type provides access to page grid placements of categories, products and product variants. For categories, the placements of the ordinary page grid are retrieved, while for products the Product Detail Page (PDP) and the corresponding pdpPagegrid is used. Product variants simply inherit all placements from their parent product.

Note

It is recommended to use the augmentation API below the ContentRoot because it is the future-proof solution with less calls and better decoupling.

The placements within a page grid can be retrieved in whole, including the complete grid structure with grid rows. Alternatively, a plain list of placements can be retrieved, optionally filtered by placement names. In the following example, only the placements "header" and "additional" are retrieved for a product:

{
      content {
    productAugmentationBySite(externalId: "PC_BRITISH_TEA", breadcrumb: ["PC_DELI", "PC_ToDrink"], siteId: "99c8ef576f385bc322564d5694df6fc2") {
      commerceRef {
        externalId
        siteId
        locale
      }
      content {
        repositoryPath
        ... on CMTeasable {
          title
          teaserText
        }
      }
      pdpPagegrid {
        placements(names: ["header", "additional"]) {
          name
          items {
            name
            type
            ... on CMTeasable {
              teaserTitle
              teaserText
              picture {
                uriTemplate
              }
            }
          }
        }
      }
    }
  }
}

In this example, you also query the title and teaserText fields of an associated content. Note that this content field is only non-null if this product is actually augmented. The same is true for the content in category augmentations - that field is only non-null if exactly this category is augmented, the field value is not inherited from the parent category.