Product Group

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

ProductGroup is a collection-scoped configuration record that groups matching products by type, manufacturer, and selected attributes so shoppers can switch between related products through option selectors.

Parent hierarchy:

• Catalog & Merchandising
• Attributes And Grouped Configurability
• Product Group

Primary implementation paths:

• packages/framework/src/Models/ProductGroup.php
• packages/framework/src/Services/ProductGroup
• packages/admin/src/Livewire/Admin/Settings/Collection/ProductGroups
• packages/framework/src/Imports/ProductGroup
• packages/framework/src/Exports/ProductGroup

What Users Can Do With It

Direct capabilities

Admin users can:

• create a product group inside a collection
• choose the product type the group applies to
• choose the attributes and display types that define the group
• build or rebuild the group
• activate or deactivate the group
• review duplicate or invalid combinations
• delete the group
• import and export product groups through dedicated Excel workflows

Indirect capabilities

Other workflows use product groups without editing the group record directly:

• products inherit group behavior from their collection, type, and manufacturer alignment
• shoppers use the resulting option selectors on product detail pages

Where It Is Managed

Channel	Role	Notes
Admin collection detail page	Direct	Product groups are managed from the collection page, not as a top-level menu
Excel import/export	Direct	Dedicated product-group import and export workflows exist
Storefront product page	Indirect	Shoppers consume the generated option combinations, not the group record itself
Generated build process	Indirect	Combination rows and options are rebuilt from the group definition

Sources:

• packages/admin/src/Livewire/Admin/Settings/Collection/ProductGroups/Block.php
• packages/admin/src/Livewire/Admin/Settings/Collection/ProductGroups/Form/CreateDialog.php
• packages/admin/src/Livewire/Admin/Settings/Collection/ProductGroups/Form/EditDialog.php
• packages/framework/src/Services/ProductGroup/ProductGroupService.php
• packages/framework/src/Imports/ProductGroup/ProductGroupImport.php
• packages/framework/src/Exports/ProductGroup/ProductGroupExport.php
• packages/storefront/src/Livewire/Storefront/Product/ProductGroupBlock.php

Channel-Level Field Coverage

Admin create dialog

The packaged create flow exposes:

• productTypeId
• selectedGroupAttributes[*].product_attribute_id
• selectedGroupAttributes[*].display_type
• autoActivate

The collection and manufacturer context are inherited from the collection page rather than chosen separately in the dialog.

Source:

• packages/admin/src/Livewire/Admin/Settings/Collection/ProductGroups/Form/CreateDialog.php
• packages/admin/src/Livewire/Admin/Settings/Collection/ProductGroups/Form/BaseDialog.php

Admin edit dialog

The packaged edit flow exposes:

• active
• the selected attribute list
• each selected attribute's display type
• rebuild behavior when attribute selections change

It also provides diagnostic views for duplicate product combinations.

Sources:

• packages/admin/src/Livewire/Admin/Settings/Collection/ProductGroups/Form/EditDialog.php
• packages/admin/src/Livewire/Admin/Settings/Collection/ProductGroups/ViewProductCombinationsDialog.php

Model fields that exist but are not directly user-entered in the packaged dialog

The model also contains fields managed automatically or inherited from context:

• product_collection_id
• product_manufacturer_id
• last_build_started_at
• last_build_completed_at

Source:

• packages/framework/src/Models/ProductGroup.php

Configuration And Data Model

Key model characteristics:

• soft-deletable
• build-status aware
• collection-scoped

Important fields:

Field	Purpose
product_type_id	the product type the group applies to
product_manufacturer_id	inherited brand/manufacturer scope
product_collection_id	collection that hosts the group
active	whether the group should be used in shopper-facing behavior
last_build_started_at, last_build_completed_at	build process markers

Supporting subordinate records:

• ProductGroupAttribute
• ProductGroupAttributeOption
• ProductGroupAttributeOptionProduct

Sources:

• packages/framework/src/Models/ProductGroup.php
• packages/framework/src/Services/ProductGroup/ProductGroupService.php

Relationships

ProductGroup directly relates to:

• productType()
• productManufacturer()
• productCollection()
• productGroupAttributes()
• productCombinations()
• matching products()

Source:

• packages/framework/src/Models/ProductGroup.php

Rules And Downstream Effects

Important rules and effects:

• a group is unique per product type, collection, and manufacturer combination
• deleting a group deletes subordinate group-attribute records
• building a group deletes existing combination data and remaps products to attribute options
• only active products matching the group's collection, type, and manufacturer are considered
• build output skips products that do not have all required attribute values
• large groups build asynchronously when they exceed the configured thresholds
• auto-activation is blocked when draft attribute options with requirements exist
• group cache tags are flushed when the group definition changes or rebuilds

Sources:

• packages/framework/src/Models/ProductGroup.php
• packages/framework/src/Services/ProductGroup/ProductGroupService.php
• packages/framework/src/Services/ProductGroup/Jobs/BuildProductGroup.php

Integrations And Automation

Excel

The product-group export includes:

• product_groups
• product_group_attributes
• attribute_options
• product_combinations

The import expects:

• product_groups
• product_group_attributes

Sources:

• packages/framework/src/Exports/ProductGroup/ProductGroupExport.php
• packages/framework/src/Imports/ProductGroup/ProductGroupImport.php
• packages/admin/src/Livewire/Admin/Tools/Excel/ImportDialog/ProductGroupImport.php

Storefront option resolution

Storefront product pages resolve product-group options through the product-group combination service and the product resource can include the generated group payload when requested.

Sources:

• packages/storefront/src/Livewire/Storefront/Product/ProductGroupBlock.php
• packages/framework/src/Http/Resources/Storefront/ProductResource.php

Where It Appears To End Users

ProductGroup is not a top-level shopper concept, but it directly shapes the product detail page experience.

It appears through:

• product-group option selectors
• alternate product switching behavior
• collection-aligned product option displays

Sources:

• packages/storefront/src/Livewire/Storefront/Product/ProductGroupBlock.php
• packages/storefront/src/Livewire/Storefront/Product/Page.php
• packages/framework/src/Http/Resources/Storefront/ProductResource.php

Current Documentation Takeaways

• ProductGroup is a real merchandising engine, not just a supporting pivot record.
• The packaged admin product-group workflow is collection-owned and intentionally separate from the ordinary product edit flow.
• Product groups are the clearest place where admin configuration, Excel tooling, build automation, and shopper-facing UX all meet in the Catalog domain.

Open Questions

• This first pass did not identify a packaged API surface for product groups; the primary management channels appear to be admin UI plus Excel.
• Some display-type requirement behavior is visible in the services, but the exact operator guidance for each display type should be documented in a later product-group deep dive.