Sitecore Experience Commerce: Working with Digital Sellable Items – Part 2

In this article, we look closer at the techincal details behind how digital sellable items are managed in the Commerce Engine, which in turn drives storefront functionality.

For an introduction to digital sellable items and how to configure them, see Working with Digital Sellable Items - Part 1.

Technical Implementation Details

See the Terminology Definitions for further explanation of tag types and Digital Item Tag Types for the default tags available, which are used throughout this article.

Inventory

Digital sellable items are always available for purchase, which I think of as having perpetual inventory. This functionality is driven by the AvailabilityAlwaysPolicy.

During the IGetSellableItemPipeline, the EnsureSellableItemAvailabilityPoliciesBlock replaces the sellable item's AvailabilityPolicy with the AvailabilityAlwaysPolicy where one or more of the sellable item's tags match the digital item tags.

See Digital Item Tags for the full list of default tags.

Plugin.Catalog.IGetSellableItemPipeline
  Plugin.Catalog.PrepGetSellableItemBlock
  Core.IFindEntityPipeline
  Plugin.Catalog.FilterSellableItemVariantsBlock 
  Plugin.Catalog.FormatComposerViewPropertyBlock 
  Plugin.Catalog.IPostGetSellableItemPipeline 
    Plugin.Catalog.GetSellableItemCatalogBlock 
    Plugin.Catalog.ICalculateSellableItemPricesPipeline
    Plugin.Catalog.AddSellableItemToContextBlock
    Plugin.Availability.EnsureSellableItemAvailabilityPoliciesBlock
    Plugin.Availability.IPopulateItemAvailabilityPipeline

Inventory Rules - Standalone Sellable Item

Summary: The AvailabilityAlwaysPolicy (perpetual inventory) is dependent on digital item tags being configured on the sellable item.

Inventory Rules - Sellable Items with Variants

Summary: The AvailabilityAlwaysPolicy (perpetual inventory) is dependent on the digital item tags being configured on the sellable item, which propagates to all variants. Configuring digital item tags on the variants will not have any effect, therefore perpetual inventory will either apply to all variants or no variants.

Cart Lines

When adding an item to the cart, the IAddCartLinePipeline runs, with the notable registered pipeline block or pipeline is IPopulateValidateCartPipeline, which syncs cart lines with the data from the sellable item entities. In part this is achieved with by calling the IGetSellableItemPipeline (more detail above in Inventory) for each cart line, which is important as the subsequent blocks that utilise the presence of AvailabilityAlwaysPolicy.

Plugin.Carts.IAddCartLinePipeline
  Plugin.Catalog.ValidateSellableItemBlock
  Plugin.Carts.AddCartLineBlock
  Plugin.Carts.AddContactBlock
  Plugin.Carts.IPopulateValidateCartPipeline
  Plugin.GiftCards.AddCartLineGiftCardBlock
  Plugin.DigitalItems.AddCartLineDigitalProductBlock
  Plugin.DigitalItems.AddCartLineWarrantyBlock
  Plugin.DigitalItems.AddCartLineInstallationBlock
  Plugin.Carts.ICalculateCartLinesPipeline
  Plugin.Carts.ICalculateCartPipeline
  Plugin.Carts.PersistCartBlock

These subsequent pipeline blocks, AddCartLineDigitalProductBlock, AddCartLineWarrantyBlock, and AddCartLineInstallationBlock, determine if the newly added cart line is a digital item type by comparing the cart line tags against its respective set of digital item type tag lists in conjunction with the AvailabilityAlwaysPolicy. Similarly, the AddCartLineGiftCardBlock also compares cart line tags against gift card tags, but ignores the presence of the AvailabilityAlwaysPolicy.

If the cart line has been identified as a digital sellable item, it will be split the cart line out into single quantity lines, so that each digital sellable item can have unique fulfillment details, coming up in the checkout's delivery step.

Plugin.Carts.IAddCartLinePipeline
  Plugin.Catalog.ValidateSellableItemBlock
  Plugin.Carts.AddCartLineBlock
  Plugin.Carts.AddContactBlock
  Plugin.Carts.IPopulateValidateCartPipeline
  Plugin.GiftCards.AddCartLineGiftCardBlock
  Plugin.DigitalItems.AddCartLineDigitalProductBlock
  Plugin.DigitalItems.AddCartLineWarrantyBlock
  Plugin.DigitalItems.AddCartLineInstallationBlock
  Plugin.Carts.ICalculateCartLinesPipeline
  Plugin.Carts.ICalculateCartPipeline
  Plugin.Carts.PersistCartBlock

Cart Line Rules - Standalone Sellable Item

Summary: Configuring a sellable item with one or more digital item type tags and one or more digital item tags (triggering perpetual inventory) will split cart lines into single quantity lines. Where one or more gift card tags are configured to a sellable item, this will also split cart lines and does not require a digital item tag configured.

Cart Line Rules - Sellable Items with Variants

Summary: Similar to sellable item configurations, the only difference for configuring sellable items with variants is that the digital item tags or gift card tags need to apply to the variants themselves.

Consideration: Variants inherit its parent sellable item's tags if not configured, however if a tag is configured on a variant it will not inherit the tags from the parent sellable item.

* includes tags inherited from parent sellable item

Cart Fulfillment Option Types

For the checkout's delivery step, the IGetCartFulfillmentOptionsPipeline is executed within the GetCartFulfillmentOptions API, returning the available fulfillment option types for the storefront.

Plugin.Fulfillment.IGetCartFulfillmentOptionsPipeline
  Plugin.Fulfillment.FilterCartFulfillmentOptionsBlock

The key pipeline block is the FilterCartFulfillmentOptionsBlock, which roughly provides the following logic.

  1. Retrieves all fulfillment option types associated to the storefront.
  2. Removes the "SplitShipping" (Deliver Items Individually - split shipment) type if there is only one cart line.
  3. Removes the physical fulfillment option type, "ShipToMe" (Ship To Address), where a cart contains digital sellable items, identified by the AvailabilityAlwaysPolicy.
  4. Removes the digital fulfillment option type, "Digital" (Digital Delivery), where a cart contains physical sellable items.

The storefront's fulfillment options are located in the Sitecore Content Editor at /sitecore/Commerce/Commerce Control Panel/Storefront Settings/Storefronts/<storefront>/Fulfillment Configuration.

Cart Fulfillment Rules - Standalone Sellable Item

Summary: The digital fulfillment option types are dependent on the presence of the AvailabilityAlwaysPolicy (perpetual inventory) on the sellable item, rather than comparing the digital item type or gift card tags as one would expect.

Cart Fulfillment Rules - Sellable Items with Variants

Summary: The digital fulfillment option types are dependent on the presence of the AvailabilityAlwaysPolicy (perpetual inventory) on the sellable item, rather than comparing the digital item type or gift card tags on the variants as one would expect.

Consideration: This is also another instance where the parent sellable item drives the behaviour of all of its variants, so if you selling books, for example, and wanted to sell the digital PDF version, there is a customisation here to think about.

Cart Line Fulfillment Option Types

Where the split shipping option type is selected during the checkout's delivery step, each cart line will require their own fulfillment option type, of which the available types per cart line are determined via the GetCartLineFulfillmentOptions API.

Plugin.Fulfillment.IGetCartLineFulfillmentOptionsPipeline
  Plugin.Fulfillment.FilterCartLineFulfillmentOptionsBlock

The key pipeline block in this pipeline is the FilterCartLineFulfillmentOptionsBlock, which has similar logic to the FilterCartFulfillmentOptionsBlock, but focuses on each cart line in isolation.

  1. Retrieves all fulfillment option types associated to the storefront.
  2. Removes the "SplitShipping" / (Deliver Items Individually - split shipment) type as this option is not applicable for individual line items.
  3. Removes the physical fulfillment option type, "ShipToMe" (Ship To Address), where the cart line is a digital sellable item, identified by the "entitlement" tag.
  4. Removes the digital fulfillment option type, "Digital" (Digital Delivery), where the cart line is a physical sellable item.

You may have noticed that the "entitlement" tag is being utilised instead of the AvailabilityAlwaysPolicy as per the FilterCartFulfillmentOptionsBlock. Although the "entitlement" tag does exist in the Digital Item Tags, effectually meaning that the sellable item will still contain the AvailablityAlwaysPolicy, it's important note to take for identifying how digital sellable items need to be configured, so we don't run into any surprises in the storefront.

Cart Line Fulfillment Rules - Standalone Sellable Item

Summary: The digital fulfillment option types for cart lines are dependent on the presence of the "entitlement" tag on the sellable item, which by default is equivalent to the AvailabilityAlwaysPolicy, rather than comparing the digital item type or gift card tags as one would expect.

Cart Line Fulfillment Rules - Sellable Items with Variants

Summary: The digital fulfillment option types for cart lines are dependent on the presence of the "entitlement" tag on the variant, which by default is equivalent to the AvailabilityAlwaysPolicy, rather than comparing the digital item type or gift card tags as one would expect.

* includes tags inherited from parent sellable item

Entitlements

Entitlements are provisioned during the released order minion. The GenerateOrderEntitlementsBlock is the central point for creating the entitlements, calling the IProvisionEntitlementsPipeline to handle each digital item type.

Plugin.Orders.IReleasedOrdersMinionPipeline
  Plugin.Fulfillment.GenerateOrderShipmentBlock
  Plugin.Fulfillment.GenerateOrderLinesShipmentBlock
  Plugin.Entitlements.GenerateOrderEntitlementsBlock
  Plugin.FaultInjection.MinionFaultBlock
  Plugin.FaultInjection.SettlePaymentFaultBlock
  Plugin.Sample.Payments.Braintree.SettleOrderSalesActivitiesBlock
  Plugin.Orders.MoveReleasedOrderBlock
Plugin.Entitlements.IProvisionEntitlementsPipeline
  Plugin.Entitlements.ProvisionEntitlementsBlock
  Plugin.GiftCards.ProvisionGiftCardEntitlementsBlock
  Plugin.DigitalItems.ProvisionInstallationEntitlementsBlock
  Plugin.DigitalItems.ProvisionDigitalProductEntitlementsBlock
  Plugin.DigitalItems.ProvisionWarrantyEntitlementsBlock

For orders to receive entitlements, both the AvailabilityAlwaysPolicy and a tag from their respective digital item type must be present, this includes the gift card entitlements, which in previous areas didn't validate against the AvailabilityAlwaysPolicy.

Once the Entitlement entity has been created it is then associated to the order as an Entity Reference.

If the order was placed by a registered customer, the entitlement will also be associated to the order as an Entity Reference.

Entitlement Rules - Standalone Sellable Item

Summary: Both the AvailabilityAlwaysPolicy and a digital item type tag will need to be associated to the sellable item to generate the respective entitlement and create an entity reference to it on the order.

Entitlement Rules - Sellable Items with Variants

Summary: The AvailabilityAlwaysPolicy must be present on the parent sellable item, while a digital item type tag will need to be associated to the variant to generate the respective entitlement and create an entity reference to it on the order.

* includes tags inherited from parent sellable item

Entitlement Rules - Customer Entitlements

Summary: Piggybacking off of the base entitlement rules above, if an entitlement has been created for an order and the customer was registered at the time the order was placed, the respective digital item type entitlement will be added to the Customer commerce entity.

Appendix

Terminology Definitions

  • Digital item tags: Tags configured in DigitalItemTagsPolicy.TagList.
  • Digital type tags: Any of the digital product tags, installation tags, or warranty tags.
  • Gift card tags: Tags configured in GiftCardTagsPolicy.TagList.
  • Digital product tags: Tags configured in KnownEntitlementsTags.DigitalProductTags.
  • Installation tags: Tags configured in KnownEntitlementsTags.InstallationTags.
  • Warranty tags: Tags configured in KnownEntitlementsTags.WarrantyTags.

Summary

We have covered how digital sellable items are treated throughout the Sitecore Commerce Engine. These are not limitations of the platform, as you are free to customise the functionality to your specific business requirements, but should be taken into consideration when evaluating business requirements and performing a gap analysis against platform functionality.

Sitecore Experience Commerce: Working with Digital Sellable Items – Part 1

In this article, we will review the difference between physical and digital sellable items, while focusing on the lesser documented digital sellable items. We will also review how to configure digital sellable items in the business manager.

For a more technical details behind the implementation of digital sellable items, see Working with Digital Sellable Items - Part 2.

Sellable Item Classifications

Sellable items can either represent physical or digital items. The following high-level overviews detail some of the discerning factors between the two classifications of sellable items.

Physical Sellable Items

Physical sellable items are any tangible product that a customer can purchase and have delivered. This is the default product type when creating sellable items via the Merchandising Manager in Sitecore Commerce.

Inventory

With physical items, inventory is required to track stock levels and prevent overselling.

Fulfillment Option Types

When purchasing physical items, during the checkout delivery step, a customer typically enters a delivery address of where the items will be delivered to, or selects a 'click and collect' style fulfillment option type where they can pick up the items from.

The SXA Storefront provides the common 'deliver to address' (physical) fulfillment option type.

Digital Sellable Items

Digital sellable items represent non-tangible products that a customer can purchase that entitle the customer to a form of product or service. Examples of digital sellable items include services, such as installation, warranties, subscriptions, digital downloads, online access, and digital currency (gift cards).

Inventory

As digital sellable items are non-tangible, they do not require inventory information to be associated to them. This can also be thought of as having perpetual inventory, therefore always being available for purchase.

Fulfillment Option Types

For digital sellable item purchases, the SXA Storefront provides a digital delivery sample implementation intended for digital gift card purchases, consisting of a recipient email and custom message, so the digital gift card can be personalised and delivered via email to the intended recipient.

Alternately, for other digital item fulfillment option types, custom implementations would be required to handle these scenarios, based on the client's requirements. Some ideas of requirements are as follows:

  • Services: A custom form, potentially with a third party integration, to create a booking system.
  • Warranties: A custom form to register the sellable item that the warranty was purchased for.
  • Subscriptions: A custom form to register the subscription's recipient details.
  • Digital Downloads: A custom form containing requesting the email address to send the digital download link to, or perhaps the user account functionality is customised to provide access to digital downloads.
  • Online access: Similar to digital downloads, the user may be given access to content via their logged in account, which may not require additional details to be taken during the Delivery step, however may require the user to make the purchase via a registered account.

Cart Lines

Digital sellable items are also separated into their own line items, e.g. when adding a digital sellable item with quantity of 2 this will create 2 cart lines with a quantity of 1, rather than 1 cart line with a quantity of 2. This provides the customer with the ability to input unique delivery information for each item during the checkout delivery step.

Entitlements

Another differentiating factor of digital sellable items are entitlements, which are registered to the order and customer account (where users are registered at the time of purchase), so that customer service representatives can view the current state of each entitlement.

Entitlements provides a basic implementation and a great starting point for customisation to meet business requirements.

Order Summary with entitlements
Customer Summary with entitements

Configuring Digital Sellable Items

Digital sellable items are determined by applying the appropriate Digital Sellable Item Tags on the sellable item and its variants. Let's review this together.

In the Business Tools,

  1. Navigate to the Merchandising Manager
  2. Locate an existing new sellable item or create a new sellable item and navigate to the Sellable Item page view
  3. Follow either Configuring Standalone Sellable Items or Configuring Sellable Item With Variants
  4. Ensure the sellable item has a valid list price and/or price card with an active price snapshot, so that the sellable item is purchasable
  5. Publish the sellable item

Configuring Standalone Sellable Items

  1. Add the appropriate tag that represents a Digital Item.
  2. Add the appropriate tag that represents the desired type of Digital Item Type.
    This will likely be the same tag as the Digital Item, therefore not required, however it is good to validate that the tags match, especially if custom tags have been assigned to the digital item and digital item type tag policies.
  3. Add the tag "entitlement".
Sellable item tags

Configuring Sellable Items With Variants

  1. On the sellable item, add the appropriate tag that represents a Digital Item.
  2. On each variant:
    1. Add the appropriate tag that represents the desired type of Digital Item Type.
    2. Add the tag "entitlement".

Note: Technically, the variants inherit tags from the parent sellable item only if no tags have been specified on the variant. Configuring any tags on a variant will remove the inherited tags from the variant, therefore these instructions specify the fool-proof solution.

Sellable item tags
Variant tags

Digital Sellable Item Tags

The following tables contain the default tags that are used to classify sellable items as digital and their digital item types.

Note: Tags for digital sellable items are not treated as case-sensitive.

Digital Item Tags

ClassificationDefault Tags
Digital Itementitlement
service
installation
subscription
digitalsubscription
warranty
onlinetraining
onlinelearning
giftcards

Digital Item Type Tags

TypeDefault Tags
Virtual Gift Cardgiftcards
Digital ProductOnlineTraining
OnlineLearning
Subscription
DigitalSubscription
Warranty Warranty
InstallationInstallation
Service