Relationship definitions

Current version: 10.1

Sitecore Experience Commerce helps business users increase sales by providing the ability to create relationships between sellable items for cross-sells and upsells, using the Sitecore Experience Commerce Business Tools.

A cross-sell relationship is one that identifies an additional product that is related to the product a customer is buying, or has already bought. For example, if a customer had added an XSound CD Bluetooth In-Dash Receiver, the store might also show a set of XSound 6 1 2” 2-Way Coaxial Car Speakers as a related product.

An upsell relationship is one that shows customers that there are different, higher-priced versions or models of the product that they’re browsing that might be better for their needs. For example, if a customer is browsing the XSound 1” Coaxial Tweeters that have a list price of $39.99, you might want to set up an upsell relationship to additionally show the XSound .75” Coaxial Tweeters that have a list price of $59.99.


Relationships are not versioned. All entity versions have the same defined relationships. This means if you make a change to the relationships associated with one entity version, the change is automatically applied to all versions. Changes to relationships are automatically reflected on the live site if any of the versions are already published. The only exceptions are BundleToSellableItem and BundleToSellableItemVariant, which are versioned and can be different with each version.

Commerce entity relationship definitions

Sitecore XC comes with default relationship definitions that pre-establish the type of relationships that can exist between Commerce entities such as catalogs, categories, and sellable items. These default base relationship definitions allow you to create your own product (or entity) associations, for cross-sell or upsells, in your own catalogs.

Sitecore XC provides the following default relationship definitions between Commerce entities (such as catalogs, categories, or sellable items) that you can leverage to create your cross-sell and upsell relationship definitions.

  • Sitecore.Commerce.Plugin.Catalog.SellableItem, Sitecore.Commerce.Plugin.Catalog: Pre-defines a sellable item-to-sellable item relationship type. This is the most common type of relationship definition in the context of merchandising. You use this type of relationship definitions to create an association between sellable items for upsells and cross-sells. The sample Habitat catalog comes with pre-defined relationship examples.

  • Sitecore.Commerce.Plugin.Catalog.Category, Sitecore.Commerce.Plugin.Catalog: Defines a category-to-category relationship type.

  • Sitecore.Commerce.Plugin.Catalog.Catalog, Sitecore.Commerce.Plugin.Catalog: Defines a catalog-to-category or catalog-to-sellable item relationship.

Cross-sell relationship definitions in the sample Habitat catalog

The sample catalogs (for example, HabitatMaster) include the following default relationship definitions that are typical examples of upsell or cross-sell definitions:

Default relation definitions

(HabitatMaster sample catalog)



A cross-sell relationship for installation entitlement products. For example, if a customer is buying a dishwasher, the store might also show an installation service that the customer can add to their order.


A cross-sell relationship for different products that are related to the product the customer is buying.


A cross-sell relationship for training products. For example, if a customer is buying a complex software product, the store might also show possible online training courses that the customer can add to their order.


A cross-sell relationship for warranty products. For example, if a customer is buying a dishwasher, the store might also show possible extended warranties the customer can add to their order.


Relationship definitions are specific to an environment ID. For example, the default relationship definitions listed above are specific to the environment ID (artifactStoreID) that is associated with the default HabitatShops environment. If your deployment defines custom environments, you do not have these predefined relationship definitions. You must create your own.

Do you have some feedback for us?

If you have suggestions for improving this article,