Broadleaf Microservices
  • v1.0.0-latest-prod

Products and Variants

Data Model

Product Data Model
Figure 1. Product and Related Entities Data Model

Products

Products are the central concept within the Broadleaf catalog. Browsing, searching, detail pages are all done by product. A Product can have a SKU, along with pricing information about the product. This allows a Product to be sold individually in the store without any extra setup.

BLC_PRODUCT

Field Definition

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

ACTIVE_START_DATE

Start of when this product should be active.

ACTIVE_END_DATE

End when this product is not longer active. Unset indicates that it is always active

ATTRIBUTES

Dynamic attributes that are a part of the product. This is an admin-centered concept allowing additional information to be stored on a product without modifying the domain directly.

AVAILABLE_ONLINE

Whether the Product has available inventory to fulfill online orders

COST

The cost of manufacturing or procuring the product by the seller. Primarily used in pricing algorithms such as calculating the price based on margin.

CURRENCY

The currency of all prices on the product.

PRICING_KEY

System-wide unique identifier to configure specific pricing for the product. Relevant if pricing data is managed in a separate system or data store, like the Broadleaf pricing services.

DEFAULT_PRICE

The default price to sell the product at. This is superseded by SALE_PRICE. All Variants of a product inherit this.

MSRP

Suggested retail price for the product. This is generally only used for display and should not have any true pricing logic tied to it.

SALE_PRICE

Indicates that this product is on sale and at what price. Supersedes DEFAULT_PRICE if present.

DESCRIPTION

Description of the product that can include HTML to display to customers.

DEPTH

The depth dimension of this product. This is a scalar value; see DIMENSIONAL_UNITS to set the units.

HEIGHT

The height dimension of this product. This is a scalar value; see DIMENSIONAL_UNITS to set the units.

WIDTH

The width dimension of this product. This is a scalar value; see DIMENSIONAL_UNITS to set the units.

DIMENSION_UNITS

The unit for the various dimensions such as INCHES or METERS.

WEIGHT

The weight of the product. This is a scalar value; see WEIGHT_UNITS to set the units.

WEIGHT_UNITS

The units for WEIGHT such as POUNDS or KILOGRAMS.

DISCOUNTABLE

Whether the product can receive discounts.

ELIGIBLE_FOR_PICKUP

Whether the product can be picked-up at a store or physical location rather than shipped.

FULFILLMENT_FLAT_RATES

A map of flat rates for fulfilling (e.g., shipping) this product for a particular fulfillment option type (e.g., standard shipping). Depending on if the option is configured to use flat rates, this flat rate will be used in calculating the cost of fulfilling this product. The key of the map is the type of the fulfillment option such as FIXED_STANDARD or BANDED_PRICE_EXPRESS.

INCLUDED_PRODUCTS

Additional products that are always included with the product, no matter what. Used to configure "bundles" or "kits". See Included Products for more info.

INDIVIDUALLY_SOLD

If this product or any of its variants can be sold individually in the store, or if they must be apart of another product as an add-on. Usually if a product is not individually sold then it should also not show up in search results.

INVENTORY_CHECK_STRATEGY

Defines when the product’s inventory should be checked for availability. Values include NEVER and ADD_TO_CART.

INVENTORY_RESERVATION_STRATEGY

Defines when the product’s inventory should be reserved. Values include NEVER, ADD_TO_CART, and SUBMIT_ORDER.

INVENTORY_TYPE

Defines the type of inventory held for the product such as PHYSICAL or VIRTUAL.

KEYWORDS

Additional search terms that should be used when customers search for this product. These can be used in the <meta name="keywords" /> tag and in an external search service such as Solr.

MERCHANDISING_PRODUCT

This product is not sold itself, but is a sort of container for subordinate items such as Variants selected through ProductOptions. In other words, this means that the variants are sold rather than the product itself, which simply serves as a way to tie the variants together in a configurable way. An example of this would a t-shirt that has configurable colors and sizes.

MERGING_TYPE

Determines how this Product should merge with other similar items when it gets added to a cart. This will override the global setting on item merging. Out-of-box supported values are COMBINE, SEPARATE (every add-to-cart request results in a new line item), and REJECT_OR_IGNORE (duplicate add-requests are either ignored or rejected with an error message).

META_DESCRIPTION

sed for SEO data in <meta description=""> in a product detail page. If this is unset, DESCRIPTION will be used.

META_TITLE

Used for SEO data in <title> tag in a product detail page. If this is unset, then NAME will be used.

NAME

Customer-facing name of this product. This is inherited by any Variants, which can also override it.

IS_ONLINE

Whether or not this product should be visible at all in the store. A product that is offline is not searchable, visible, or purchasable.

OPTIONS

Drives additional information that the customer should enter when purchasing this product. See the ProductOptions document for more details.

REVIEWS_NUMBER_OF_REVIEWS

For simplified recording of user reviews of a product, this is the total number of reviews.

REVIEWS_RATING

For simplified recording of user reviews of a product, this is the overall rating from reviews.

REVIEWS_RATING_UNITS

For simplified recording of user reviews of a product, this is the unit of measure for the rating, e.g., stars, thumbs, etc.

SEARCHABLE

Determines whether this product shows up in customer search results.

SKU

The Stock Keeping Unit of the product. This can also match the SKU of a Variant to define it as the default variant to display.

UPC

The Universal Product Code.

URI

SEO-friendly URI to identify this product. This is usually generated with some URL-safe version of the primary category’s name along with a url-friendly version of NAME.

TAX_CODE

The tax code for this product.

BRAND_CONTEXT_ID

Context ID of the related Data Driven Enum that represents brand.

MERCHANDISING_TYPE_CONTEXT_ID

Context ID of the related Data Driven Enum that represents merchandising type.

TARGET_DEMOGRAPHIC_CONTEXT_ID

Context ID of the related Data Driven Enum that represents target demographic.

EXTERNAL_ID

This is an arbitrary ID, typically assigned by or used by 1st or 3rd party systems that are not Broadleaf.

MIN_THRESHOLD

The minimum count of this product that must be added in a cart.

MAX_THRESHOLD

The maximum count of this product that must be added in a cart.

PRODUCT_TYPE

Defines the type of the product. This affects how the product is displayed and managed in the admin UI, how it is handled by cart and order operations, and how it gets indexed by Search Services.

BUSINESS_TYPE

Defines the type of the product as it relates to the business. If null, the PRODUCT_TYPE will be used. This affects how the product is displayed and managed in the admin UI.

TAGS

A list of simple labels used to categorize the product

Included Products

An IncludedProduct represents a fixed bundling of additional items with a parent Product that are always included with it. That means, when the Product is added to the cart, additional dependent cart items are created for each IncludedProduct. This domain allows specifying another Product or another Product’s Variants as "included" with the parent Product. Additionally, it allows overriding the display name and pricing of that underlying item.

Tip
For configurable bundles that give the customer the ability to select multiple items or specify quantities, see ProductOptions.

Variants

Variants are specific instances of a Product that contain their own SKU. Variants provide the ability to have a specific instance of a general product. The classic example of using Variants is selling different size t-shirts, where pricing and inventory levels are managed for each specific size. Each size has its own Variant, complete with its own SKU. If you sold t-shirts in specific colors as well, each color and size combination would be its own variation, again complete with its own SKU and specific pricing and inventory information.

Since Variants are designed to be specific representations of a containing Product, Variants are not merchandised by themselves. Instead, the parent Product is merchandised (has its own detail page and shows up in searches), and then the customer has an opportunity to select which particular Variant they want to purchase from that Product.

Important
Variants can not be shared between multiple Products, and moving Variants between Products is not an operation that Broadleaf supports.

Certain fields can be managed at both the Product and Variant level. Fields defined at the Variant level serve as overrides to those fields at the Product level. The default fields are:

  • Name

  • Price

  • Online flag

  • Discountable flag

  • Weight and Dimensions

  • Cost

  • UPC

  • SKU

Common customizations to Broadleaf might include adding additional fields that can be managed at both the Product and Variant level. Generally this will be required in order to support both scenarios to add a simple Product and a Product with multiple variants.

Continuing with the t-shirt example, the size options are managed through ProductOptions. A common step in setting up variants is to generate variants based on VARIANT_DISTINGUISHING type ProductOptions that have a set of defined allowedValues. For example, consider that I have the following ProductOptions configured with the following values:

  1. Shirt Sizes

    • Small

    • Medium

    • Large

  2. Shirt Colors

    • Red

    • White

    • Blue

Broadleaf can then automatically generate Variants with the following combinations from those 2 options:

  1. Small Blue

  2. Small White

  3. Small Red

  4. Medium Blue

  5. Medium White

  6. Medium Red

  7. Large Blue

  8. Large White

  9. Large Red

Tip
A SKU code will automatically be generated for each new Variant and a prefix to add to each can be specified prior to generation.

When you set up Products in this way, you generally also do not sell the parent Product; therefore, it is common for the Product to share a SKU with one of the Variants marking that Variant as the default. This can mean that when visiting a product details page, the options for the default Variant will be preselected for the customer.

BLC_VARIANT

Note
Fields shared with BLC_PRODUCT (e.g., NAME, DEFAULT_PRICE) will override the parent product’s values if set.
Field Definition

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

PRODUCT_CONTEXT_ID

Context ID of the parent Product.

ACTIVE_START_DATE

Start of when this variant should be active.

ACTIVE_END_DATE

End when this variant is not longer active. Unset indicates that it is always active

ATTRIBUTES

Dynamic attributes that are a part of the variant. This is an admin-centered concept allowing additional information to be stored on a variant without modifying the domain directly.

COST

The cost of manufacturing or procuring the variant by the seller. Primarily used in pricing algorithms such as calculating the price based on margin.

DEFAULT_PRICE

The default price to sell the variant at. This is superseded by SALE_PRICE.

SALE_PRICE

Indicates that this variant is on sale and at what price. Supersedes DEFAULT_PRICE if present.

DESCRIPTION

Description of the variant that can include HTML to display to customers.

DEPTH

The depth dimension of this variant. This is a scalar value; see DIMENSIONAL_UNITS to set the units.

HEIGHT

The height dimension of this variant. This is a scalar value; see DIMENSIONAL_UNITS to set the units.

WIDTH

The width dimension of this variant. This is a scalar value; see DIMENSIONAL_UNITS to set the units.

DIMENSIONAL_UNITS

The unit for the various dimensions such as INCHES or METERS.

WEIGHT

The weight of the variant. This is a scalar value; see WEIGHT_UNITS to set the units.

WEIGHT_UNITS

The units for WEIGHT such as POUNDS or KILOGRAMS.

DISCOUNTABLE

Whether the variant can receive discounts.

FULFILLMENT_FLAT_RATES

A map of flat rates for fulfilling (e.g., shipping) this variant for a particular fulfillment option type (e.g., standard shipping). Depending on if the option is configured to use flat rates, this flat rate will be used in calculating the cost of fulfilling this variant. The key of the map is the type of the fulfillment option such as FIXED_STANDARD or BANDED_PRICE_EXPRESS.

INVENTORY_CHECK_STRATEGY

Defines when the variant’s inventory should be checked for availability. Values include NEVER and ADD_TO_CART.

INVENTORY_RESERVATION_STRATEGY

Defines when the variant’s inventory should be reserved. Values include NEVER, ADD_TO_CART, and SUBMIT_ORDER.

INVENTORY_TYPE

Defines the type of inventory held for the variant such as PHYSICAL or VIRTUAL.

NAME

Customer-facing name of this variant. This is inherited by any Variants, which can also override it.

IS_ONLINE

Whether or not this variant should be visible at all in the store. A variant that is offline is not searchable, visible, or purchasable.

OPTIONS_VALUES

Helper to make this particular variant uniquely identifiable across multiple variants for the same product. Keys correspond to attribute name while values correspond to one of the allowed values. See Variants for an example or the ProductOptions document for more details on options.

REVIEWS_NUMBER_OF_REVIEWS

For simplified recording of user reviews of a variant, this is the total number of reviews.

REVIEWS_RATING

For simplified recording of user reviews of a variant, this is the overall rating from reviews.

REVIEWS_RATING_UNITS

For simplified recording of user reviews of a variant, this is the unit of measure for the rating, e.g., stars, thumbs, etc.

SKU

The Stock Keeping Unit of the variant. This can also match the SKU of a Variant to define it as the default variant to display.

UPC

The Universal Product Code.

Promotional Products

A join entity that associates Products to each other in a many to many relationship, including additional information about the association. Typically this is used to specify cross-sale and up-sale products to display on a product details page.

BLC_PROMOTIONAL_PRODUCT

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

PRODUCT_CONTEXT_ID

Context ID of the owning Product

PROMOTIONAL_PRODUCT_CONTEXT_ID

Context ID of the Product being promoted

PROMOTIONAL_PRODUCT_TYPE

The type of the promotion being made such as CROSS_SALE or UP_SALE.

SORTING

Defines the sort order of this promotional product relative to all others belonging to a Product.

PROMOTIONAL_MESSAGE

A message to display to customers along with the promoted product.

Product Assets

An EntityAsset associated with a Product.

Tip
EntityAssets encapsulates information related to stored, digital content such as images, videos, or text files, that belong to a particular entity.

This can be marked as the primary (or default) asset to be displayed in search, browse, or product details pages. Additional assets can also be associated with a Product and tied to its Variants by use of tags.

BLC_PRODUCT_ASSET

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

PRODUCT_CONTEXT_ID

Context ID of the owning Product

IS_PRIMARY

Whether this is the default asset to display for the Product.

SORTING

Defines the sort order of this asset relative to all others belonging to a Product.

TENANT_ID

Context ID of the Tenant this asset belongs to. Used for resolving the actual asset content.

APPLICATION_ID

Context ID of the Application this asset belongs to. Used for resolving the actual asset content.

TYPE

Describes the general type of the asset. This is used to determine how to render the asset on the frontend such as IMAGE, PDF, or VIDEO.

PROVIDER

The name of the provider that is hosting the asset. For assets hosted by the asset service itself, this should be set to BROADLEAF.

URL

The location used to resolve this asset. If the PROVIDER is BROADLEAF, then this will be a relative URL such as /icon.png. For other providers, this will be the fully qualified URL such as https://www.youtube.com/watch?v=abcdefg.

EMBED_CODE

If TYPE is EMBED_CODE, then this field holds the HTML to be embedded. This field is mutually exclusive with URL.

ALT_TEXT

Text that corresponds to the HTML alt attribute that should be used when this asset is rendered in a browser.

TITLE

Text that corresponds to the HTML title attribute that should be used when this asset is rendered in a browser.

Asset Tags

A product asset tag represents additional, descriptive or identifying information about an asset. These can be used to associate a Product’s asset to a particular Variant.

BLC_PRODUCT_ASSET_TAG

Field Description

PRODUCT_ASSET_ID

The ID of the parent asset.

TAG

The actual tag value.

Broadleaf Common Data Features

Products, Variants, Promotional Products, and Product Assets are Catalog Trackable, which includes Sandbox Trackable behavior.