Learning PathModule

Inheritance modes

Configure how Associates and their roles flow down a Business Unit hierarchy, and predict the result.

Ask about this Page

Copy for LLM

View as Markdown

After completing this page, you should be able to:

Explain how BusinessUnitAssociateMode controls which Associates a child unit inherits.
Explain how the inheritance setting on each role assignment controls whether it cascades.
Predict the effective Associates and permissions at each level of a hierarchy.

In a Business Unit hierarchy, you often want the people who manage a parent Company to also act in its Divisions, without re-adding them to every Division by hand. commercetools supports this through associate inheritance, controlled by two independent settings. Getting them wrong silently exposes or hides Associates at child units, so it is worth tracing the behavior precisely.

Two settings control inheritance

Associate inheritance depends on a setting at the child unit and a setting on each role assignment at the parent.

associateMode (BusinessUnitAssociateMode) is set on the child Business Unit and decides whether it accepts inherited Associates at all:
- Explicit: the unit uses only its directly assigned Associates and inherits none.
- ExplicitAndFromParent: the unit uses its direct Associates and eligible Associates inherited from its parent.
inheritance (AssociateRoleInheritanceMode) is set on each role assignment at the parent and decides whether that assignment is allowed to cascade:
- Enabled: the assignment can be inherited by child units.
- Disabled (the default): the assignment stays at the unit where it is defined.

A Company is always Explicit because it has no parent. A Division defaults to ExplicitAndFromParent, so it is ready to inherit, but it inherits nothing until a parent assignment is explicitly marked inheritance: Enabled.

Both conditions must be met

For an Associate to be inherited by a child unit, both of the following must be true:

The child unit's associateMode is ExplicitAndFromParent.
A parent unit has at least one Associate whose role assignment has inheritance: Enabled.

If either condition is missing, no inheritance occurs. This is why a default Division, which is ExplicitAndFromParent but whose parent has no Enabled assignments, still shows no inherited Associates. For the canonical statement of these conditions, see Conditions for inheritance in the API reference.

In the diagram, Dana's admin assignment is Enabled, so it cascades to Residential, which is ExplicitAndFromParent. Sam's buyer assignment is Disabled, so it stays at the Company. Commercial is Explicit, so it inherits nothing from the parent regardless of the parent's settings.

The set of inherited Associates appears in a Business Unit's inheritedAssociates field. Reading the Residential Division shows Dana inherited from the parent, alongside its own explicit Associates. Each entry records where the assignment came from in associateRoleAssignments.

{
  "key": "pacific-residential",
  "associateMode": "ExplicitAndFromParent",
  "inheritedAssociates": [
    {
      "customer": {
        "typeId": "customer",
        "id": "d4a17b90-aaaa-bbbb-cccc-100000000001"
      },
      "associateRoleAssignments": [
        {
          "associateRole": {
            "typeId": "associate-role",
            "key": "company-administrator"
          },
          "source": {
            "typeId": "business-unit",
            "key": "pacific-property-group"
          }
        }
      ]
    }
  ]
}

Like inheritedStores from Module 1, this field is eventually consistent, so it may lag briefly after a change higher in the hierarchy.

Permissions accumulate

When an Associate holds roles both directly and through inheritance, their effective permissions are the sum of all those roles. There is no precedence or override: an inherited role adds its permissions to whatever the Associate already has at that unit.

This means an administrator inherited from the parent Company keeps their management permissions in the Division, and any buyer role assigned directly in the Division adds to them. Design inheritable roles with this accumulation in mind, so you do not unintentionally grant broad permissions deep in the hierarchy. See Accumulative permissions of inherited roles in the API reference for the canonical description.

Inheritance is one part of a larger matrix

Associate inheritance sits alongside the other inheritance behaviors you saw in Module 1. The following matrix summarizes what a Division can inherit and what it must always define for itself.

Aspect	Inherits?	Mechanism
Associates	Conditionally	`associateMode: ExplicitAndFromParent` on the child unit
Associate role assignments	Per assignment	`inheritance: Enabled` or `Disabled` (default `Disabled`) on each assignment
Stores	Conditionally	`storeMode: FromParent` (Store Override Rule, Module 1)
Approval Rules	Conditionally	`approvalRuleMode: ExplicitAndFromParent` (Module 7)
Addresses	Never	Always explicit on each Business Unit
Custom Fields	Never	Always explicit on each Business Unit

Inheriting Associates does not solve the addresses requirement from Module 1. A Division that inherits its Associates and Stores from its parent still requires its own shipping and billing addresses for checkout to succeed. A Division with inherited people but no addresses is a common and easily missed cause of B2B checkout failure.

Worked example: Pacific Property Group inheritance

Pacific Property Group wants its company administrator, Dana, to manage both Divisions, while each Division's buyers stay local to their own Division.

At the Company, Dana holds an administrator role with the assignment set to inheritance: Enabled. The Company's own buyers hold buyer roles with inheritance: Disabled, so they do not leak into the Divisions.
The Residential Division keeps the default associateMode: ExplicitAndFromParent. It therefore inherits Dana (admin) from the Company and adds its own buyer, Priya, directly. Dana's effective permissions in Residential are her admin permissions; Priya's are her buyer permissions.
The Commercial Division is set to associateMode: Explicit because the client wants it fully isolated. It inherits no one, not even Dana, and lists its buyer Lee directly.
Both Divisions are given their own addresses, because addresses never inherit.

Tracing it: Residential sees Dana (inherited) plus Priya (explicit); Commercial sees only Lee (explicit). Dana manages Residential without being re-added there, while the company's own buyers never appear in either Division.

Key takeaways

associateMode on the child unit (Explicit or ExplicitAndFromParent) decides whether it inherits Associates at all.
inheritance on each parent role assignment (Enabled or Disabled, default Disabled) decides whether that assignment cascades.
Both conditions must be met for inheritance to occur; a default Division inherits nothing until a parent assignment is Enabled.
An Associate's effective permissions are the sum of their direct and inherited roles, with no override.
Inherited Associates appear in inheritedAssociates and are eventually consistent; addresses and Custom Fields never inherit.

Inheritance modes

Configure how Associates and their roles flow down a Business Unit hierarchy, and predict the result.

Two settings control inheritance.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Both conditions must be met.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Permissions accumulate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Inheritance is one part of a larger matrix.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Worked example: Pacific Property Group inheritance.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Key takeaways.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Test your knowledge.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}