Commerce Product Catalog

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

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

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