Set up governance categories

Governance categories add a second, independent layer of permissions on top of your standard Category permissions. Use them when different teams, brands, or business units need different access to products that already share the same Merchandising Category tree.

What are governance categories?

By default, access to products in Akeneo PIM is controlled by permissions set directly on your category trees, under Settings > Categories. You can have several category trees, and each one's permissions apply independently. At this stage, there is no "Merchandising" label anywhere in the interface.

Once you enable the governance category tree feature, your existing category trees are relabeled Merchandising trees, and a new, single Governance tree becomes available. The Governance tree has its own permissions, which apply on top of your Merchandising trees' permissions.

This is useful when your organization manages products across multiple brands, business units, or regions, and different teams need different levels of access to the same products, even when those products sit in the same Merchandising Category.

When to use governance categories

• You manage product information across separate teams, each with unique access requirements.
• Some teams share Merchandising Categories but must not see each other's products within those shared categories.
• You need to restrict access by brand or business unit without duplicating your Merchandising Category tree.

Before you start

• You must have admin access to Akeneo PIM.
• Governance categories require the feature to be enabled in System > Configuration (see below).
• You must have User Groups configured before you can assign governance category permissions. See Manage your User Groups.

Enable governance categories in Akeneo PIM

To use governance categories in Akeneo PIM, an admin must first activate the feature in the system configuration.

1. In Akeneo PIM, go to System > Configuration.
2. In the Governance category tree section, set Enable governance category tree to Yes.
3. Click Save.

Once enabled, a Governance tab appears in Settings > Categories, alongside the Merchandising tab for your standard Category trees.

Create a governance category tree

You can only create one governance Category tree in Akeneo PIM.

1. In Akeneo PIM, go to Settings > Categories.
2. Click Create tree.

In the creation modal, select the Governance tile.

Enter a Code for the tree (required) and, optionally, a Label.

1. Click Create.

Once the governance tree is created, you can add categories to it the same way you add categories to a Merchandising tree.

Set permissions on governance categories

After creating governance categories, assign User Group permissions to each category exactly as you would for Merchandising Categories. See Set rights on your catalog, rights depending on the categories for the full steps.

Each governance category supports three access levels per User Group:

• Edit: users in this group can view and edit products in this category.
• View: users in this group can view but not edit products in this category.
• No rights: products in this category are hidden from users in this group.

How governance permissions work

When a product is classified in a governance category, the PIM applies the governance permission on top of the user's Merchandising Category permission. The user receives the strictest permission from both, following the "two locks" rule described above.

Key rules:

• If a product has no governance category, only Merchandising Category permissions apply.
• If a product is in a governance category where the user has No rights, the user cannot see the product, regardless of their Merchandising Category permission.
• If a product is in a Merchandising Category where the user has No rights, the user cannot see the product, regardless of their governance category permission.
• A product must be classified in at least one Merchandising Category and at least one governance category for both layers to apply.

How the two permissions combine:

Find the user's governance permission in the left column and their Merchandising permission along the top; the cell where they meet is the resulting access. Edit only survives if both sides allow it, and No rights on either side always wins, the "two locks" rule from earlier.

Example: two-brand setup

Imagine you manage two brands, AwesomeBrand and NewBrand, each handled by a separate team. You create:

• One governance tree called Brands, with two categories: AwesomeBrand and NewBrand.
• One Merchandising tree called Product Ranges, with two categories: Tops and Accessories.
• Four User Groups: Tops AwesomeBrand, Accessories AwesomeBrand, Tops NewBrand, Accessories NewBrand.

Governance Category permissions (Brands tree):

Merchandising Category permissions (Product Ranges tree):

Resulting access per product and user group:

Product #3 has no governance category (N/A), so only its Merchandising permission determines access.

What users see in the product grid

An admin with full access sees the complete catalog. A brand manager sees only the products in their brand's governance category. Users in different User Groups see different subsets of the catalog, even when browsing the same Merchandising Category.

The screenshot above shows the full product catalog as seen by an admin with access to all governance and Merchandising Categories.

The screenshot above shows the filtered product catalog as seen by a brand manager assigned to one brand's governance category, only products classified in their permitted governance category are visible.

The screenshot above shows the filtered product catalog for a second brand manager User Group, showing a different subset of products from the same Merchandising Category.

Users can only view and export products classified in governance categories they have permission to access.

Frequently asked questions

Do I need to use governance categories if I already use Merchandising Categories?
No. Governance categories are an optional second layer. If you never create a governance Category tree, only your Merchandising Category permissions apply, exactly as before.

What happens to products that aren't in a governance category?
Only Merchandising Category permissions apply to them. A product needs to be in both a Merchandising Category and a governance category for the governance layer to take effect.

Can I create more than one governance category tree?
No. Akeneo PIM supports a single governance Category tree per instance.

Can I convert an existing Merchandising tree into a governance tree, or the other way around?
No. The tree type is set when the tree is created and cannot be changed afterward.

If a user has Edit rights on the Merchandising side but only View rights on the governance side, what can they do?
They can only view the product. The stricter of the two permissions always applies, following the "two locks" rule.

Can I filter the product grid or an export by both a Merchandising and a governance category at the same time?
Not directly in the grid or export profile UI. See the API workaround in the Limitations section below.

Limitations and tips

• Tree type is permanent: once created, a Merchandising tree cannot be converted to a governance tree, and vice versa.
• One governance tree only: you can only create one governance Category tree per Akeneo PIM instance.
• Grid and export filtering: you cannot filter on both a Merchandising tree and a governance tree simultaneously in the product grid or in export profiles.
• API filtering with both trees: if you need to filter on both a Merchandising and a governance category in API requests, use one of these approaches:
  • Pass two separate categories filters in your API request: {{url}}/api/rest/v1/products?search={"categories":[{"operator":"IN","value":["GovernanceCategory1"]}]}&search={"categories":[{"operator":"IN","value":["MerchandisingCategory1"]}]}&with_count=true
  • Create an API user with specific governance category permissions, then apply Merchandising Category filters in the API call.