Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 28 ยท Platform APIs and Data

Catalog, Products and Price Books

Understand product types (master, variant, set, bundle), categories, price books, promotions and ProductSearchModel in Salesforce Commerce Cloud.

A store is only as good as its catalog. In Salesforce B2C Commerce, the catalog holds your products and categories, price books hold the prices, promotions change what shoppers pay, and a search index makes it all findable. These four pieces are separate on purpose: merchants maintain them with different schedules, different people and different import feeds, and the Script API reflects that separation.

This lesson explains the product types you will meet, how categories and catalogs relate to a site, how a price is chosen from price books, where promotions fit, and how ProductSearchModel builds search and category pages. For the platform-neutral ideas behind these concepts, read Product Catalog, Variants and Options, Pricing Models and The Promotions Engine; this page does not repeat them. Real platform code is read-only here. The two stand-ins in plain JavaScript model variation resolution and price selection, and each says what is real and what is simplified.

Product types

Every product in the catalog has a type, and the type decides how it can be sold.

  • Standard product: a simple item that can be bought as it is, with its own price and inventory.
  • Master product: a template that defines variation attributes (for example color and size) and their values. A master is not sold itself; it has no price or stock of its own, and shoppers see it as one product detail page.
  • Variant: a purchasable product that belongs to a master and has one value for each variation attribute, such as the red, size M one. The variant has its own SKU, price and inventory.
  • Variation group: a set of variants that share some attribute values (for instance all variants in one color), so that search and tiles can show that group on its own. It is optional and mostly a merchandising tool.
  • Product set: products shown together on one page, such as an outfit. The shopper adds the members individually.
  • Product bundle: several products sold as one unit. The bundle has its own price, and the bundled products appear as part of it in the basket.
  • Option product: a product with product options such as a warranty or an engraving, each with its own values and price adjustments.

You can ask any product what it is:

JavaScript
var ProductMgr = require('dw/catalog/ProductMgr');
var product = ProductMgr.getProduct('tee-red-m');

product.isMaster();        // true for a master
product.isVariant();       // true for a variant
product.isBundle();
product.isProductSet();
product.isOptionProduct();

if (product.isVariant()) {
    var master = product.masterProduct;
}

Variation models

The ProductVariationModel of a product (product.variationModel) answers questions such as: which attributes exist, which values does each have, which variants match a selection, and which values are still available. In SFRA this is wrapped for you by the product model and the ProductFactory, as described in Models, Decorators and Helpers, but the logic underneath is always the same.

JavaScript
var variationModel = master.variationModel;
var attributes = variationModel.productVariationAttributes;  // color, size

variationModel.setSelectedAttributeValue('color', 'red');
var sizes = variationModel.getAllValues(variationModel.getProductVariationAttribute('size'));

var variant = variationModel.selectedVariant;   // null until every attribute is chosen

The pattern a product page follows: show every value of each attribute, grey out the ones that cannot lead to an available variant, and when all attributes are selected, show the selected variant's price, images and availability. The first TryIt runs exactly that logic on plain data. What is real: attribute values, a selection narrowing the variants, and a variant appearing only when the selection is complete. What is simplified: the platform also has sorting of values, images per attribute value, orderable-vs-in-stock rules and separate online flags for variants.

flowchart TD
    M["Master: Linen Tee<br/>(not sold itself)"] --> V1["Variant red / S<br/>SKU tee-red-s"]
    M --> V2["Variant red / M<br/>SKU tee-red-m"]
    M --> V3["Variant blue / M<br/>SKU tee-blue-m"]
    V1 --> G1["Variation group: red"]
    V2 --> G1
    M --> A["Variation attributes:<br/>color, size"]

A master defines the attributes; each variant has one value per attribute and is the real item that is sold.

JS Resolving a variant from a selection (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In the output, (L) in parentheses means "no in-stock variant leads there", and [red] marks the chosen value. The selection red / M finds a variant that exists but has no stock; a real storefront would show it as unavailable.

Categories and catalogs

Products live in catalogs. A catalog contains a category tree and product assignments. A site points to one site catalog (its storefront catalog) and to a root of the navigation. Each product has a primary category (used for breadcrumbs and some features) and can be assigned to additional categories for merchandising. Categories have online flags, dates, display names per locale, custom attributes and a position in the tree.

JavaScript
var CatalogMgr = require('dw/catalog/CatalogMgr');
var category = CatalogMgr.getCategory('mens-shirts');
var subcategories = category.onlineSubCategories;
var products = category.onlineProducts;     // use search for large categories, not this

Reading category.onlineProducts loads products in memory; for category pages use the search model below, which uses the search index and handles refinements, sorting and paging. A catalog can be shared by several sites or each site can have its own, and a separate navigation catalog is possible when the menu should not follow the product catalog. These are architectural decisions made early on a project.

Price books

Prices are not stored on the product page. They live in price books: named lists of prices for a currency, each entry giving a product (usually a variant or standard product) and a price, optionally with quantity tiers (price per unit from 5 pieces, from 10 pieces). Common structures are one list price book and one sale price book per currency, and price books can inherit from a parent. Price books are assigned to sites in Business Manager.

At runtime the ProductPriceModel (product.priceModel) chooses the price: for the shopper's currency and quantity, among the price books active for the site, the lowest applicable price wins. That is why a sale is simply a second price book with lower entries and a schedule. The list price shown as a strikethrough usually comes from a specific "list" price book that the storefront reads explicitly (priceModel.getPriceBookPrice(...)).

JavaScript
var priceModel = product.priceModel;
var price = priceModel.price;                 // lowest applicable price, a Money object
var listPrice = priceModel.getPriceBookPrice('usd-list-prices');
var isSale = price.available && listPrice.available && price.value < listPrice.value;
var tiers = priceModel.getPriceTable();       // quantity breaks

Money.available is false when no price exists, so check it before using value. Handle money as Money objects or integer cents, as explained in Money as Integers.

Promotions

Promotions live in campaigns and are separate from price books. A campaign has dates (or is always on), and it contains promotions such as "20% off all dresses", "buy two, get one free" or "free shipping over $100". The three families are product promotions, order promotions and shipping promotions. They can depend on customer groups, source codes and coupons.

Promotions are not baked into priceModel.price. They are applied during basket calculation: PromotionMgr.applyDiscounts(basket) evaluates the active promotions against the basket and adds price adjustments to the line items. For listing pages, you can ask for a promotional price by looking up the active product promotions of a product. Rules that cross stores, such as stacking and priority, are discussed in The Promotions Engine, and the calculation order is shown in Basket, Checkout and Order Flow.

The second TryIt chooses a price from several price books and then applies a promotion on top. It is a model of the idea, using integer cents. What is real: currency matching, the lowest price winning, tier selection by quantity, and promotions as a separate step. What is simplified: price book inheritance, schedules and the exact set of promotion types.

JS Choosing a price from price books, then a promotion (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice the quantity-10 line: the list book has a 22.00 tier, but the sale book's single price (19.99) is still lower, so the sale wins. If the sale price book were removed from the site's active books, tiers would apply again.

Searching the catalog

dw.catalog.ProductSearchModel runs searches against the search index, not the database. It handles category browsing, phrases, refinements, sorting and paging, and it is what SFRA's search helpers use.

JavaScript
var ProductSearchModel = require('dw/catalog/ProductSearchModel');
var CatalogMgr = require('dw/catalog/CatalogMgr');

var search = new ProductSearchModel();
search.setCategoryID('mens-shirts');
search.setSearchPhrase('linen');
search.addRefinementValues('color', 'Blue');
search.setSortingRule(CatalogMgr.getSortingRule('price-low-to-high'));
search.setRecursiveCategorySearch(true);
search.search();

var hits = search.getProductSearchHits();   // iterator of ProductSearchHit
while (hits.hasNext()) {
    var hit = hits.next();
    var representedProduct = hit.product;   // often the master or a variation group
}
hits.close();

Hits usually represent the master or variation group, not every variant, so a tile can show a product once while offering color swatches. Because search reads an index, a newly imported product is not found until the index is rebuilt; plan index rebuilds into your import jobs, as in Jobs, Feeds and Import/Export. Remember the iterator rules from The Script API and Common Classes: page through results with the model's paging methods, and close iterators you do not exhaust.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which product type is the template that defines variation attributes but is not purchasable by itself?

    A master defines attributes such as color and size and their values. The variants beneath it are the items that have SKUs, prices and stock.
  2. 2. A product has entries in a list price book (25.00) and an active sale price book (19.99), same currency. Which price does the price model return?

    Among the price books active for the site and currency, the lowest applicable price is chosen, which is why a sale can be modeled as a separate price book.
  3. 3. Where are promotions applied to a basket?

    Promotions live in campaigns and are evaluated against the basket during calculation, adding price adjustments to the line items.
  4. 4. Why should category pages use ProductSearchModel instead of category.onlineProducts?

    Loading all products of a category into memory is slow and hits limits. The search model reads the index and handles the usual storefront needs.
  5. 5. A product was imported an hour ago and does not appear in search. What is a likely cause?

    Search reads an index. New or changed catalog data only becomes searchable after indexing, so imports are usually followed by an index rebuild.

Summary

  • Product types decide how an item is sold: standard, master, variant, variation group, set, bundle and option product.
  • The variation model narrows variants by the shopper's selection; the product page greys out values that lead nowhere.
  • A site uses a catalog with a category tree; products have a primary category and extra assignments.
  • Prices come from price books (per currency, with quantity tiers); the lowest applicable price wins, and sales are usually separate price books.
  • Promotions live in campaigns and are applied during basket calculation, not inside the price model.
  • ProductSearchModel searches the index for category and search pages; remember to rebuild the index after imports.

Next: Basket, Checkout and Order Flow