Broadleaf Microservices
  • v1.0.0-latest-prod

Catalog Concepts within Cart & Checkout

Catalog Item representation

At its most basic structure, a sellable item from a catalog will contain:

  1. an ID: this is arbitrary and is used to identify the item throughout the various cart operations

  2. a SKU: this Stock Keeping Unit uniquely identifies the item for operations such as pricing and inventory

  3. the price information for this item: this is basic pricing data, and is used to perform amount calculations for the Cart & CartItems

With this in mind, Cart & Checkout is structured to retrieve and identify catalog items based on this information, without requiring other data points that may be irrelevant. In order to make this extensible regardless of the catalog item specifics, various hook points have been added to help with any overrides for specific variations of catalog item representations. For more details on the extension hook points, see Common Extension Hook Points for Catalog in Cart & Checkout.

Request Payload to an External Catalog Service

The default external catalog provider within CartOperations passes the following request payload to identify and retrieve the Catalog Item.

  1. Product ID: The ID to identify a product catalog item

    1. This is a general PIM concept to identify catalog items, but may not be targeted enough to identify the catalog item in all systems. In general, this is the default key to identify cart items within Broadleaf.

  2. Variant ID: The ID to identify a product’s variant catalog item

    1. This is a general PIM concept that is used in conjunction with the Product ID to identify catalog items for multi-SKU products, but may not be a compatible representation for the catalog item in all systems. By default in Broadleaf, this is used to narrow down the catalog item to a specific variation or "Variant" of multi-sku Products.

  3. SKU: The Stock Keeping Unit that can identify the catalog item

  4. A map of attributes: A structure to hold any additional information that should be passed to the Catalog service to identify the catalog item

For more information on this provider and its usage, see the documentation for the Catalog Provider.

Response Payload expected

Within the cart operations, we expect to retrieve catalog information to populate the Cart Items for checkout processing and cart display. The expected response is a list of generic CatalogItems as detailed in the section above.

Typically the catalog information returned would contain a richer representation than what is returned on CatalogItem for display and validations in the checkout flow. Our default representation of a CatalogItem is the which is the structure that returned by our Catalog service. If the Product and Variant domains do not meet your needs, the CatalogItem can be extended to create a custom representations for an external Catalog service.

Managing Cart Items without a backing Catalog Item

Broadleaf also supports having Cart Items that do not reference a Catalog Item. An example of these items would be our out of box use case for Cart Fees & Collect-On-Delivery payment fees.

To support other types of cart items without backing catalog items, hook points are available for business logic specific validations. See the list of extension points in the Common Extension Hook Points for Catalog in Cart & Checkout.