README

What this module does

conneqt/module-customer-assortment adds customer-specific product visibility to Magento 2.

In short, the module lets you assign products to a customer-specific assortment and then uses that assortment to:

• filter catalog search results
• block direct access to product detail pages when a product is not allowed
• support guest visibility rules for selected products and categories
• expose REST endpoints for synchronizing assortments from an external system
• optionally keep product flags and parent-product relations in sync through Magento's message queue

This is useful when not every customer should see the same catalog, or when an ERP/PIM/integration decides which SKUs a customer may buy or search for.

How it works

At a high level, the module works in four layers:

1. Assortment storage
   Customer-to-product assignments are stored in the conneqt_customer_assortment table declared in etc/db_schema.xml.

2. Sync and maintenance
   The helpers behind the REST API create, update, remove, and check assortment rows. When enabled, they also publish product update messages so Magento can update derived product state asynchronously.

3. Storefront enforcement
   Magento search and product-view flows are intercepted so shoppers only see products they are allowed to access.

4. Admin and configuration
   The module adds configuration fields and a customer admin tab so assortment behavior can be controlled and reviewed from the backend.

Request flow overview

1. Assortment data is stored per customer

The main table is etc/db_schema.xml:

• customer_id: the external/customer identifier used by the module
• product_sku: the Magento SKU that belongs to the customer assortment
• external_id: optional external reference from an upstream system
• personal_sku: optional customer-specific alias that can be searched

The module also stores customer-specific search terms in conneqt_customer_search_query.

2. API calls or internal code update the assortment

The main write/read helpers are:

• Helper/ProductAdd.php – adds or updates assortment rows and can perform cleanup
• Helper/ProductRemove.php – removes selected or all assortment rows for a customer
• Helper/ProductGet.php – reads assortment rows and SKU lists
• Helper/ProductHas.php – checks whether a customer has a SKU or any assortment at all

REST routes are declared in etc/webapi.xml, while dependency wiring for API implementations lives in etc/di.xml.

3. Product visibility is enforced on the storefront

The most important visibility flow is configured in etc/di.xml:

• Plugin/ElasticsearchPlugin.php injects assortment and guest-visibility conditions into Elasticsearch queries.
• Plugin/ProductDetailBlockPlugin.php prevents direct product-page access when a shopper should not be allowed to view the product.
• Plugin/CustomerSessionContext.php copies customer assortment information into Magento's HTTP context so cached pages and search logic can use it safely.
• Helper/CustomerAssortment.php is the central read helper used by search-related code to determine the active customer's assortment state.

4. Search is extended with assortment-specific data

The module also extends Magento search behavior:

• Model/Adapter/DataMapper/AssortmentFieldsDataProvider.php adds assortment-related fields such as guest visibility and personal SKU data to the search index payload.
• Model/Autocomplete.php customizes autocomplete providers.
• Plugin/Model/Query.php stores customer-aware search popularity data.

5. Queue consumers keep product metadata in sync

If automatic updates are enabled, Helper/ProductAdd.php publishes messages to the conneqt.assortment.product.update topic.

Queue configuration is defined in:

• etc/communication.xml
• etc/queue_publisher.xml
• etc/queue_topology.xml
• etc/queue_consumer.xml

The queue handler Model/Queue/Handler/Handler.php can:

• automatically toggle the customer_specific product attribute
• automatically add parent products for configurable, bundle, and grouped products

Installation

Install the module with Composer:

composer require conneqt/module-customer-assortment

Then enable and upgrade Magento as usual:

bin/magento module:enable Conneqt_CustomerAssortment
bin/magento setup:upgrade
bin/magento cache:flush

If you use the asynchronous product update flow, make sure the Magento queue consumer for conneqt.assortment.product.update is running in your environment.

Requirements

• PHP >= 8.1
• magento/framework
• magento/module-catalog-search ^102.0
• cweagans/composer-patches
• conneqt/m2-base >=1.0

These constraints are declared in composer.json.

Configuration

Configuration is available in the Magento admin at:

Stores → Configuration → Conneqt → Customer Assortment

The fields are declared in etc/adminhtml/system.xml.

Important settings

• Customer Id Attribute
  Selects which customer attribute the module uses as the assortment identifier. This makes it possible to use an ERP/customer number instead of Magento's internal customer entity ID.

• Automatically adjust customer specific
  When enabled, product visibility metadata is recalculated after assortment changes so products can be marked as customer-specific automatically.

• Automatically add parent product to a customers assortment
  When enabled, parent products of assigned simple products can be added automatically through the queue handler.

• No assortment full access
  Lets logged-in customers without any assortment rows see the full catalog. Guests are still handled by the guest visibility rules.

Product and category attributes added by this module

The data patches in Setup/Patch/Data create the attributes used by the visibility logic:

• Setup/Patch/Data/AddProductAttributePatch.php → customer_specific
• Setup/Patch/Data/AddVisibleForGuestsProductAttribute.php → visible_for_guests on products
• Setup/Patch/Data/AddVisibleForGuestsCategoryAttribute.php → visible_for_guests on categories
• Setup/Patch/Data/AddExcludeFromCategoryGuestVisibilityProductAttribute.php → exclude_from_category_guest_visibility

These attributes are part of the guest and customer-specific visibility checks performed in search and on the product detail page.

Admin UI

The module adds assortment-related admin UI for customer management:

• view/adminhtml/layout/customer_index_edit.xml adds an Assortment tab to the customer edit page.
• Controller/Adminhtml/Index/Assortment.php returns the layout for the customer assortment panel.
• view/adminhtml/ui_component/assortment_listing.xml defines the admin listing that shows assortment rows such as external IDs and personal SKUs.

Important files at a glance

API reference

The REST API documentation has been moved to a separate file:

• docs/api.md

That file contains the endpoint list, request payloads, and response structure for:

• add products
• remove products
• remove all products
• get products
• check whether a customer has a product

Limitations and notes

This module focuses on catalog search and direct product access. Some storefront areas may still need custom integration if they load products outside the standard search and product-view flows.

In particular, review and test:

• custom product blocks or widgets
• related products / upsells / cross-sells
• layered navigation counts
• configurable and grouped child-product visibility in custom themes
• compatibility with third-party search, merchandising, or personalization modules

Also note that the module's customerId can be mapped to a custom customer attribute, so it does not have to match Magento's default internal customer entity ID.