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.
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 |
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 |
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 |
HEIGHT |
The height dimension of this product.
This is a scalar value; see |
WIDTH |
The width dimension of this product.
This is a scalar value; see |
DIMENSION_UNITS |
The unit for the various dimensions such as |
WEIGHT |
The weight of the product.
This is a scalar value; see |
WEIGHT_UNITS |
The units for |
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 |
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 |
INVENTORY_RESERVATION_STRATEGY |
Defines when the product’s inventory should be reserved.
Values include |
INVENTORY_TYPE |
Defines the type of inventory held for the product such as |
KEYWORDS |
Additional search terms that should be used when customers search for this product.
These can be used in the |
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 |
META_DESCRIPTION |
sed for SEO data in |
META_TITLE |
Used for SEO data in |
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 |
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 |
TAGS |
A list of simple labels used to categorize the product |
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 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.
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 |
Indicates that this variant is on sale and at what price.
Supersedes |
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 |
HEIGHT |
The height dimension of this variant.
This is a scalar value; see |
WIDTH |
The width dimension of this variant.
This is a scalar value; see |
DIMENSIONAL_UNITS |
The unit for the various dimensions such as |
WEIGHT |
The weight of the variant.
This is a scalar value; see |
WEIGHT_UNITS |
The units for |
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 |
INVENTORY_CHECK_STRATEGY |
Defines when the variant’s inventory should be checked for availability.
Values include |
INVENTORY_RESERVATION_STRATEGY |
Defines when the variant’s inventory should be reserved.
Values include |
INVENTORY_TYPE |
Defines the type of inventory held for the variant such as |
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. |
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.
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 |
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. |
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.
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 |
PROVIDER |
The name of the provider that is hosting the asset.
For assets hosted by the asset service itself, this should be set to |
URL |
The location used to resolve this asset.
If the |
EMBED_CODE |
If |
ALT_TEXT |
Text that corresponds to the HTML |
TITLE |
Text that corresponds to the HTML |
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.
Field | Description |
---|---|
PRODUCT_ASSET_ID |
The ID of the parent asset. |
TAG |
The actual tag value. |
Products, Variants, Promotional Products, and Product Assets are Catalog Trackable, which includes Sandbox Trackable behavior.