Products and Variants

Table of Contents

Data Model
Products
- BLC_PRODUCT
- Included Products
Product Terms
Variants
- BLC_VARIANT
Promotional Products
- BLC_PROMOTIONAL_PRODUCT
Product Assets
- BLC_PRODUCT_ASSET
- Asset Tags
Broadleaf Common Data Features
Product Characteristics
- BLC_PRODUCT_CHARACTERISTIC

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

TERMS

A list of purchasing terms associated with the product. See Product Terms for more information.

Tip	Introduced in Catalog Service 2.2.0.

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.

Product Terms

Represents a configurable contract term for a Product. Terms are useful for configuring different prices depending on the length of the term. The default term is used for the initial display price.

These indicate the name of the term for display, the duration length and type, as well as if the term is the default to display for purchase. An example would be to allow a smartphone product to be purchased with a 36-month payment plan rather than just upfront.

Tip	Price Data can target a Product’s Terms in conjunction with its SKU or ID to handle the different prices available, e.g., set up a Price Data for $50 upfront and $30 per month recurring with terms of 36-months and then add similar terms (36-months) to the Product.

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:

Shirt Sizes
- Small
- Medium
- Large
Shirt Colors
- Red
- White
- Blue

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

Small Blue
Small White
Small Red
Medium Blue
Medium White
Medium Red
Large Blue
Large White
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

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.

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

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.

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

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.

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

Field	Description
`PRODUCT_ASSET_ID`	The ID of the parent asset.
`TAG`	The actual tag value.

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.

Product Characteristics

Tip	Introduced in Catalog Service 2.2.0.

A Product Characteristic represents the value of a Characteristic for a particular Product instance.

Note	A Product Characteristic will not be created if the Characteristic type is `VARIANT_OPTION`, but will instead be represented as a Variant Distinguishing, Attribute Choice ProductOption.

BLC_PRODUCT_CHARACTERISTIC

Field Description

Field	Description
`PRODUCT_ID`	The ID of the parent Product. This is part of the primary key.
`FIELD_NAME`	The key used to identify the related Characteristic. This is part of the primary key.
`FIELD_TYPE`	The type of value represented by this field. See CharacteristicValueType for more information.
`VALUE`	The actual value (or values) for the Product. This can be plural in the case that the cardinality on the Characteristic allows or requires such. For example, a Characteristic might represent battery features, so the Product can have a list of features like Qi Wireless Charging, Non-Removable, and Fast Battery Charging.
`CHARACTERISTIC_CONTEXT_ID`	The system ID of the parent Characteristic.

PRODUCT_ID

The ID of the parent Product. This is part of the primary key.

FIELD_NAME

The key used to identify the related Characteristic. This is part of the primary key.

FIELD_TYPE

The type of value represented by this field. See CharacteristicValueType for more information.

VALUE

The actual value (or values) for the Product. This can be plural in the case that the cardinality on the Characteristic allows or requires such. For example, a Characteristic might represent battery features, so the Product can have a list of features like Qi Wireless Charging, Non-Removable, and Fast Battery Charging.

CHARACTERISTIC_CONTEXT_ID

The system ID of the parent Characteristic.