Commerce Product Catalog

This skill activates when a practitioner needs to create, configure, or troubleshoot the B2B or B2C Commerce product catalog — including category hierarchy setup, product assignment to categories, entitlement policy configuration for buyer visibility, and product attribute/variant modeling. It does not cover CPQ catalog configuration or standard Product2/Pricebook2 data loading outside of a Commerce context.

---

Before Starting

Gather this context before working on anything in this domain:

• Confirm which WebStore record the work targets and retrieve its Id. A store can be associated with only one ProductCatalog at a time via the WebStoreCatalog junction object.
• Identify how many BuyerGroup records exist and which CommerceEntitlementPolicy records are linked to each. Buyer entitlement per product is capped at 2,000 buyer groups for search indexing — exceeding this silently drops products from search results.
• Confirm whether the store uses Salesforce Search or Einstein Search. Both require a manual search index rebuild after catalog or entitlement changes — changes do not propagate automatically.
• Check if products use attribute sets (for variants). ProductAttributeSet and ProductAttribute records drive the variant model and must be configured before Product2 variant records can be created.

---

Core Concepts

ProductCatalog and WebStoreCatalog

ProductCatalog is the top-level container for a Commerce catalog. Each store is linked to exactly one ProductCatalog through a WebStoreCatalog junction record. A single ProductCatalog can serve multiple stores, but a store may not reference multiple catalogs simultaneously. Attempting to create a second WebStoreCatalog for the same store results in a validation error.

ProductCategory records form the navigational and organizational hierarchy within a catalog. Categories are linked to their catalog via the CatalogId field on ProductCategory. Categories can be nested (parent–child) to arbitrary depth, though very deep hierarchies increase page-load time and are an operational anti-pattern.

Products are assigned to categories through ProductCategoryProduct junction records — one per Product2-per-category assignment. A product can belong to multiple categories within the same catalog.

CommerceEntitlementPolicy and Buyer Visibility

CommerceEntitlementPolicy records control which products a buyer group can see and purchase. A policy is linked to a BuyerGroup through CommerceEntitlementPolicyGroup. Products are explicitly included in a policy via CommerceEntitlementProduct records.

The platform limit that causes the most production incidents: a single product can be included in at most 2,000 buyer groups for search index purposes. If a product is assigned to more than 2,000 buyer groups (via entitlement policies), Salesforce silently excludes it from search results for those buyer groups beyond the cap. There is no error message. The product still appears via direct URL or catalog browsing, but search will not surface it.

Product Variants and Attribute Sets

Product variants in Commerce are modeled using ProductAttributeSet (the set of attributes, e.g., Color, Size) and ProductAttribute (individual attribute definitions). A parent product (Product2 with IsActive = true) holds the attribute set reference. Child variant products are separate Product2 records linked to the parent via the VariantParentId field. Each child represents a specific combination of attribute values (e.g., Blue + Large).

Attribute sets must be created and assigned to the parent product before child variants can be created. Attempting to create a variant product without a configured attribute set results in a validation error. Attribute values are stored on ProductAttributeSetProduct junction records.

Search Index Dependency

The Commerce search index is a separate, asynchronous data store derived from the catalog. It must be explicitly rebuilt — via Setup > B2B Commerce > [Store] > Search Index — after any of the following:

• Adding or removing products from categories
• Creating or modifying CommerceEntitlementPolicy records
• Activating or deactivating Product2 records
• Changing WebStoreCatalog associations

Until the index rebuild completes, buyer-facing search results will reflect the previous state.

---

Common Patterns

Pattern A: Single Catalog, Flat Category Hierarchy

When to use: Stores with fewer than 200 SKUs and a single buyer segment where all buyers see the same products.

How it works:

1. Create one ProductCatalog record.
2. Create ProductCategory records directly under the catalog (no nesting) or with one level of nesting.
3. Create ProductCategoryProduct for each Product2 → Category assignment.
4. Create one WebStoreCatalog linking the catalog to the store.
5. Create one CommerceEntitlementPolicy and one BuyerGroup; link all products to the policy.
6. Rebuild the search index.

Why not the alternative: Nesting categories deeply (3+ levels) for small catalogs adds configuration overhead and slows storefront category navigation without benefit.

Pattern B: Single Catalog, Segmented Entitlement Policies

When to use: Multiple buyer tiers (e.g., Gold, Silver, Public) need different product visibility within the same store and catalog structure.

How it works:

1. Create one ProductCatalog and assign it to the store via WebStoreCatalog.
2. Create ProductCategory records shared across all buyer tiers.
3. Create separate BuyerGroup and CommerceEntitlementPolicy per tier.
4. Assign products to the appropriate policies via CommerceEntitlementProduct records.
5. Monitor total buyer group assignments per product — stay below 2,000.
6. Rebuild the search index after any policy change.

Why not the alternative: Separate catalogs per buyer tier requires separate stores (one catalog per store) and multiplies administrative overhead. Segmented entitlement within one catalog is the canonical Commerce approach.

Pattern C: Variant Products with Attribute Sets

When to use: Products that come in multiple configurations (e.g., clothing in multiple sizes and colors, equipment in multiple voltages).

How it works:

1. Create a ProductAttributeSet record (e.g., "Apparel Attributes").
2. Create ProductAttribute records linked to the set (e.g., Color, Size).
3. Create the parent Product2 record and link the attribute set.
4. Create child Product2 variant records — one per attribute combination — with VariantParentId pointing to the parent.
5. Set attribute values on each child via ProductAttributeSetProduct.
6. Add only the parent product to ProductCategoryProduct; children are discoverable via the parent on the PDP.
7. Assign the parent and children to CommerceEntitlementProduct records as needed.

Why not the alternative: Creating separate, unrelated Product2 records for each variant breaks the storefront PDP variant selector and prevents buyers from switching between variants on the same page.

---

Decision Guidance

Situation	Recommended Approach	Reason
All buyers see the same products	Single BuyerGroup + Single EntitlementPolicy	Simplest setup; fewest records; easiest to maintain
Multiple buyer tiers, different product visibility	Multiple BuyerGroups + multiple EntitlementPolicies	Native Commerce entitlement model; stays within one catalog and one store
Need separate pricing AND separate product catalogs	Separate stores with separate catalogs	One catalog per store is a platform constraint; pricing differences alone don't require separate catalogs
Products in multiple configurations	Variant Products with ProductAttributeSet	Provides storefront variant selector UX; keeps SKU navigation coherent
Product visible in admin but missing from buyer search	Rebuild search index; verify entitlement; check 2,000 group cap	Search index is async; entitlement is separate from category assignment
Need to move product from one catalog to another	Delete ProductCategoryProduct in old catalog; create new in new catalog; check entitlement policy	Products themselves (Product2) are org-wide; catalog membership is controlled by junction records

---

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Identify the target store and current catalog. Query WebStoreCatalog for the store's WebStoreId to confirm the active ProductCatalogId. Note: only one record is allowed per store.
2. Design the category hierarchy. Sketch the top-level categories and any sub-categories. Prefer 2 levels maximum for operational simplicity. Create ProductCategory records with CatalogId pointing to the active catalog.
3. Assign products to categories. Create ProductCategoryProduct junction records for each Product2 → ProductCategory pairing. A product can belong to multiple categories.
4. Configure entitlement policies. For each buyer segment, create or verify a CommerceEntitlementPolicy linked to the appropriate BuyerGroup via CommerceEntitlementPolicyGroup. Create CommerceEntitlementProduct records for each product the segment should see. Verify total buyer group assignments per product remain under 2,000.
5. Configure variant products if applicable. Ensure ProductAttributeSet and ProductAttribute records are in place before creating child variant Product2 records. Set VariantParentId on each child.
6. Rebuild the search index. Navigate to Setup > B2B Commerce > [Store Name] > Search Index and initiate a full rebuild. Wait for the job to complete before testing buyer-facing search.
7. Validate buyer visibility end-to-end. Log in as a buyer user in the appropriate BuyerGroup, search for a product, and confirm it appears. Confirm that products outside the buyer's entitlement policy do not appear.

---

Review Checklist

Run through these before marking work in this area complete:

• WebStoreCatalog has exactly one record for the target store with the correct ProductCatalogId
• All ProductCategory records have a valid CatalogId and correct ParentCategoryId hierarchy
• ProductCategoryProduct records exist for all products that should appear in at least one category
• Each buyer group has an active CommerceEntitlementPolicy linked via CommerceEntitlementPolicyGroup
• CommerceEntitlementProduct records exist for every product the buyer group should see
• No product is assigned to more than 2,000 buyer groups across all entitlement policies
• Search index rebuild was initiated and completed successfully after all catalog and entitlement changes
• Variant products have VariantParentId set and all child variants are linked to the parent's attribute set

---

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. One catalog per store — hard constraint — A WebStore record can have exactly one active WebStoreCatalog junction. Attempting to insert a second WebStoreCatalog for the same store raises a validation rule error. To switch catalogs, delete the existing WebStoreCatalog first, then create the new one.
2. 2,000 buyer group cap is silent — If a product is included in more than 2,000 CommerceEntitlementPolicy records (and thus more than 2,000 buyer groups), it is silently excluded from search index results for buyer groups beyond the 2,000 limit. No error, no warning, no Apex trigger fires. The product still appears via direct navigation but buyers cannot discover it via search.
3. Search index does not auto-rebuild — Adding a product to a category or an entitlement policy does not trigger any automatic search reindex. Buyers will not see new products in search until an admin initiates a full or incremental index rebuild from Setup.
4. Category assignment does not equal buyer visibility — Assigning a product to a ProductCategory makes it organizationally visible in the Commerce admin but does not make it visible to buyers. Buyer visibility requires a CommerceEntitlementProduct record in the buyer group's active entitlement policy AND an up-to-date search index.
5. Variant children require attribute set before creation — A child variant Product2 record cannot be saved without an existing, valid ProductAttributeSet linked to the parent product. Creating variants before the attribute set is configured results in a validation error that does not always provide a clear field-level message in the UI.

---

Output Artifacts

Artifact	Description
ProductCatalog record	Top-level catalog container associated to the store via WebStoreCatalog
ProductCategory records	Hierarchical category structure within the catalog
ProductCategoryProduct records	Junction records assigning Product2 to categories
WebStoreCatalog record	Junction linking one ProductCatalog to one WebStore
CommerceEntitlementPolicy records	Controls which products each buyer group can see and buy
CommerceEntitlementProduct records	Junction records listing products visible under a given policy
Search Index rebuild confirmation	Setup record showing successful completion of search index rebuild
Variant configuration	ProductAttributeSet, ProductAttribute, and child Product2 records with VariantParentId set

---

Related Skills

• admin/b2b-commerce-store-setup — Use when setting up the WebStore, BuyerGroup, and storefront configuration before the catalog is populated
• data/product-catalog-data-model — Use when bulk-loading Product2, Pricebook2, and PricebookEntry records outside a Commerce context