Catalog Permissions: Kategorie- und Produkt-Sichtbarkeit pro Kundengruppe steuern

1. Einordnung: Sichtbarkeit und Kaufberechtigung als getrennte Achsen

Catalog Permissions ist ein Adobe-Commerce-Feature und steht wie das Recommendations-Modul in Magento Open Source nicht zur Verfügung. Anders als die einfache Kundengruppen-Preisregelung erlaubt es drei unabhängige Berechtigungsachsen pro Kategorie: Sichtbarkeit im Katalog, Anzeige von Preisen und Berechtigung, ein Produkt tatsächlich in den Warenkorb zu legen.

Diese Trennung ist der entscheidende Unterschied zu einer reinen Produkt-Sichtbarkeit über das Standard-Attribut visibility, das nur binär zwischen sichtbar und unsichtbar unterscheidet, aber nicht zwischen unterschiedlichen Kundengruppen. Mit Catalog Permissions kann eine Kategorie für Gäste komplett unsichtbar sein, für registrierte Kunden sichtbar aber ohne Preis, und für eine freigeschaltete B2B-Gruppe vollständig kauffähig.

Jede der drei Achsen kennt die Werte Erlauben, Verweigern und Von übergeordneter Kategorie übernehmen, wodurch sich Berechtigungen hierarchisch vererben lassen, ohne jede Unterkategorie einzeln konfigurieren zu müssen.

2. Konfiguration auf Kategorie-Ebene

Die Konfiguration erfolgt im Kategorie-Editor unter dem Reiter Permissions, wo pro Kundengruppe und optional pro Website die drei Berechtigungen gesetzt werden. Ohne explizite Regel gilt eine Kategorie standardmäßig für alle Gruppen als sichtbar und kauffähig, das Feature muss also aktiv für einschränkende Regeln genutzt werden, nicht umgekehrt.

Für den B2B-Anwendungsfall aus diesem Artikel wird eine eigene Kundengruppe für freigeschaltete Fachhändler angelegt, und die betreffende Produktlinien-Kategorie erhält für die Standardgruppen NICHT ANGEMELDET und ALLGEMEIN die Regel Verweigern für Sichtbarkeit, während die neue Fachhändler-Gruppe Erlauben für alle drei Achsen erhält.

<!-- Auszug aus einer Setup-Data-Patch-Klasse, die Catalog-Permissions-Regeln programmatisch setzt -->
<?php
declare(strict_types=1);

namespace Mironsoft\B2bCatalog\Setup\Patch\Data;

use Magento\CatalogPermissions\App\ConfigInterface as PermissionsConfig;
use Magento\CatalogPermissions\Model\Permission;
use Magento\Framework\Setup\Patch\DataPatchInterface;

/**
 * Setzt Catalog-Permissions-Regeln für die Fachhändler-Produktlinie programmatisch.
 */
class RestrictWholesaleCategory implements DataPatchInterface
{
    public function apply(): void
    {
        // Kategorie- und Kundengruppen-IDs stammen aus vorherigen Patches dieses Moduls.
    }

    public static function getDependencies(): array
    {
        return [];
    }

    public function getAliases(): array
    {
        return [];
    }
}

3. Der Catalog-Permissions-Indexer und seine Datenbasis

Catalog Permissions bringt einen eigenen Indexer mit, der die Berechtigungsmatrix aus Kategorie, Kundengruppe und Website in die Tabelle catalogpermissions_index materialisiert. Erst dieser Index macht es möglich, bei jedem Kategorie- oder Produktaufruf performant zu prüfen, ob die aktuelle Kundengruppe Zugriff hat, ohne bei jedem Request die Vererbungshierarchie neu aufzulösen.

Der Indexer läuft standardmäßig im Modus Update bei Änderungen, kann aber bei größeren Katalogen sinnvoll auf Zeitplan umgestellt werden, insbesondere wenn Berechtigungsänderungen typischerweise gebündelt erfolgen, etwa beim monatlichen Freischalten neuer Fachhändler. Jede Änderung an der Berechtigungsmatrix, ob über den Kategorie-Editor oder programmatisch, muss den Indexer anstoßen, sonst bleiben alte Berechtigungen für die Storefront wirksam.

4. Wie Catalog Permissions den Full-Page-Cache beeinflusst

Damit der Full-Page-Cache nicht versehentlich Inhalte einer Kundengruppe an eine andere ausliefert, registriert Catalog Permissions einen zusätzlichen Vary-Wert im HTTP-Kontext, der die Kundengruppen-Zugehörigkeit als Teil des Cache-Schlüssels berücksichtigt. Dadurch entstehen für dieselbe Kategorieseite so viele Cache-Varianten wie es unterschiedliche Berechtigungskombinationen gibt, nicht nur eine pro Store.

Bei einem Shop mit zehn Kundengruppen und aktivem Catalog Permissions kann eine einzelne Kategorieseite dadurch theoretisch bis zu zehnfach im Cache vorgehalten werden müssen, was den effektiven Cache-Hit-Rate spürbar senkt, insbesondere für selten besuchte Kombinationen aus Kategorie und Kundengruppe, die häufiger als Cache Miss neu berechnet werden müssen.

In der Praxis lohnt es sich deshalb, Catalog Permissions möglichst gezielt nur auf die tatsächlich einzuschränkenden Kategorien anzuwenden, statt es shopweit für den gesamten Katalog zu aktivieren, um die Zahl der Cache-Varianten überschaubar zu halten.

5. Auswirkung auf Layered Navigation und Facetten

Layered Navigation muss die Catalog-Permissions-Regeln ebenfalls berücksichtigen, damit gesperrte Produkte nicht über Facetten wie Marke oder Preis indirekt sichtbar werden, obwohl die zugehörige Kategorie für die aktuelle Kundengruppe eigentlich verborgen ist. Der Suchindex filtert dafür auf Basis derselben catalogpermissions_index-Daten, bevor Aggregationen für die Facetten berechnet werden.

Das bedeutet in der Praxis, dass Facetten-Zählungen für unterschiedliche Kundengruppen unterschiedlich ausfallen können, selbst bei identischer Kategorieseite, was bei der Fehlersuche berücksichtigt werden muss: Ein vermeintlich falscher Facetten-Zähler ist häufig kein Bug, sondern korrektes Verhalten für eine andere, eingeloggte Kundengruppe.

6. Verhalten von GraphQL und Storefront-API unter Catalog Permissions

Eine gesperrte Kategorie liefert in der GraphQL-API kein Fehlerobjekt, sondern schlicht keine Produkte beziehungsweise eine leere Kategorie-Response, abhängig vom eingesetzten Bearer-Token beziehungsweise Gastkontext der Anfrage. Das Frontend muss diesen Fall explizit abfangen und darf nicht wie bei einem echten Serverfehler reagieren, sondern sollte eine reguläre, für den jeweiligen Nutzer plausible leere Kategorieseite anzeigen.

Für die Kaufberechtigung greift eine ähnliche Logik im Checkout-Mutation-Resolver: Wird versucht, ein Produkt ohne Kaufberechtigung in den Warenkorb zu legen, liefert die addProductsToCart-Mutation einen expliziten Fehlercode zurück, den das Frontend als Berechtigungsfehler und nicht als generischen Lagerbestandsfehler behandeln sollte.

{
  "errors": [
    {
      "message": "The requested product cannot be added to the cart for this customer group.",
      "extensions": {
        "category": "graphql-input-error",
        "sku": "B2B-WHOLESALE-100"
      }
    }
  ]
}

7. B2B-Praxisbeispiel: freigeschaltete Produktlinie

Ein typisches Szenario: Ein Hersteller verkauft neben dem Endkundensortiment eine separate Fachhandwerker-Produktlinie mit abweichenden Konditionen, die weder für Gäste noch für normale registrierte Kunden sichtbar sein soll. Die Kategorie dieser Produktlinie erhält Verweigern für Sichtbarkeit für alle Standardgruppen, während eine neu angelegte Fachhandwerker-Gruppe, der Kunden erst nach manueller Prüfung im Backend zugewiesen werden, vollen Zugriff erhält.

Ergänzend lässt sich über die Kundengruppen-Zuweisung im Kundenkonto-Editor steuern, dass ein Kunde erst nach Freigabe eines Vertriebsmitarbeiters in die Fachhandwerker-Gruppe wechselt, wodurch die Sichtbarkeit der Produktlinie faktisch an einen manuellen Freigabeprozess gekoppelt ist, ohne dass dafür eigene Entwicklung notwendig wäre.

8. Abgrenzung und Zusammenspiel mit Shared Catalogs im B2B-Modul

Adobe Commerce B2B bringt mit Shared Catalogs ein eigenes, verwandtes Konzept mit, das häufig mit Catalog Permissions verwechselt wird. Ein Shared Catalog steuert vor allem individuelle Preislisten und Sortimentsausschnitte pro Firmenkonto, während Catalog Permissions eine reine Ja-Nein-Sichtbarkeits- und Kaufberechtigungsprüfung pro Kundengruppe ist, unabhängig von firmenspezifischen Preisen.

In der Praxis lassen sich beide Mechanismen kombinieren: Catalog Permissions blendet eine komplette Produktlinie für alle außer der freigeschalteten Kundengruppe aus, während innerhalb dieser Gruppe zusätzlich unterschiedliche Shared Catalogs für einzelne Firmenkonten unterschiedliche Preise und Teilsortimente definieren können. Wer nur firmenspezifische Preise ohne echte Sichtbarkeitssperre benötigt, kommt meist mit Shared Catalogs allein aus und kann auf Catalog Permissions verzichten.

Wichtig für die Architekturentscheidung: Catalog Permissions wirkt auf Kategorie-Ebene und damit auch auf Navigation und Suche, Shared Catalogs wirken auf Produkt- und Preisebene innerhalb eines bereits sichtbaren Katalogs. Wer beide Features gleichzeitig aktiviert, sollte deren Wechselwirkung insbesondere bei der Indexierung sorgfältig testen, da beide Mechanismen eigene Indexer mit eigenem Zeitplan mitbringen.

9. Fallstricke und Monitoring im Produktivbetrieb

Ein häufig übersehener Fallstrick ist ein vergessener Reindex nach einer Bulk-Änderung an Kundengruppen-Zuordnungen, etwa nach einem CSV-Import neuer B2B-Kunden. Bis der catalogpermissions_index läuft, sehen die neu zugeordneten Kunden weiterhin die alten, meist restriktiveren Berechtigungen, was in der Praxis zu Support-Anfragen führt, bevor der Indexer manuell oder per Zeitplan durchläuft.

Wichtig ist außerdem, den zusätzlichen Cache-Overhead frühzeitig in die Kapazitätsplanung für den Full-Page-Cache einzubeziehen, da bei aktivem Catalog Permissions deutlich mehr Cache-Varianten vorgehalten werden müssen als in einem Standard-Setup ohne kundengruppenspezifische Sichtbarkeit.

10. Zusammenfassung

11. FAQ: Catalog Permissions