Learning PathModule

Business Units: Company and Division

Model buyer organizations using the Business Unit resource and design hierarchies that match real organizational structures.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Distinguish between Company and Division Business Unit types.

  • Design Business Unit hierarchies for different buyer organization structures.

  • Decide when to model a buyer as a flat Company or as a hierarchy of Divisions.

The Business Unit resource models a buyer organization. It is the foundation of every B2B setup: it scopes which Associates can act for the company, which Stores the company buys from, and which Approval Rules apply.
A Business Unit has one of two types, set through the unitType field:
  • Company: the top level of a buyer organization. A Company must not have a parentUnit.
  • Division: a unit within a Company or another Division. A Division has a parentUnit reference to a Company or a higher-order Division.

Create a Company

A Company is the root of a buyer organization. The minimum a Company needs is a unitType, a unique key, and a name. The key is immutable; for its exact format constraints, see the key field of BusinessUnit in the API reference.
POST /{projectKey}/business-units HTTP/1.1
Content-Type: application/json

{
  "unitType": "Company",
  "key": "horizon-hotels",
  "name": "Horizon Hotels"
}
The response shows the defaults the platform applies to a Company. Note that topLevelUnit points back to the Company itself, and storeMode, associateMode, and approvalRuleMode are all Explicit: a Company never inherits because it has no parent.
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 1,
  "unitType": "Company",
  "key": "horizon-hotels",
  "name": "Horizon Hotels",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "horizon-hotels"
  },
  "associateMode": "Explicit",
  "associates": [],
  "approvalRuleMode": "Explicit"
}

Create a Division

A Division models a sub-unit of a Company, such as a regional office or a department. Unlike a Company, a Division requires a parentUnit that references a Company or another Division.
POST /{projectKey}/business-units HTTP/1.1
Content-Type: application/json

{
  "unitType": "Division",
  "key": "pacific-residential",
  "name": "Pacific Property Group Residential",
  "parentUnit": {
    "typeId": "business-unit",
    "key": "pacific-property-group"
  }
}
When you create a Division, the platform applies inheritance-friendly defaults: storeMode defaults to FromParent, while associateMode and approvalRuleMode default to ExplicitAndFromParent. These defaults let a Division inherit Stores, Associates, and Approval Rules from its parent unless you override them. You configure inheritance in detail on the next page and, for Associates, in Inheritance modes in Module 2.

Hierarchy depth and structure

You can organize Business Units hierarchically up to a maximum of 5 levels, with the top level always being a Company. Each top-level unit can include up to 4 000 Divisions, including direct and indirect children.

Every Business Unit carries two reference fields that locate it in the hierarchy:

  • parentUnit: the immediate parent. Present only on Divisions.
  • topLevelUnit: the Company at the root of the hierarchy. Present on every unit; for a Company it references itself.

When to use a hierarchy versus a flat Company

Not every buyer needs Divisions. Modeling a flat Company is simpler and easier to manage, so reach for a hierarchy only when the organization's requirements call for it. Use the following decision table to justify the structure.

RequirementRecommended structure
Divisions share products and pricesParent Company with Divisions inheriting the Store
Divisions need different assortmentsDedicated Store and Product Selection per Division
Divisions share prices but need separate order visibilityDivisions inheriting the parent Store, with Business Unit-scoped order queries
Different legal entities or tax regimesSeparate Companies, with no hierarchy between them
One-time or single-project buyerFlat Company with no Divisions

Worked example: structuring two buyers

Apply the decision table to two Zen Electron Trade buyers.

Horizon Hotels is a single procurement team buying a known set of products for their hotels. There are no separate departments with different assortments or pricing, and no requirement to separate order visibility. This maps to the "one-time or single-project buyer" and "shared products and prices" rows, so model Horizon Hotels as a flat Company with no Divisions.
Pacific Property Group has two divisions, Residential and Commercial, that buy different product ranges for different kinds of developments, while company headquarters retains oversight of all orders. Different assortments per division maps to the "Divisions need different assortments" row. Model Pacific Property Group as a Company with two Divisions. Store assignment is covered on the next page; Product Selection per Division is covered in Module 3.
Setup sequencing dependency: in the Merchant Center, the Business Unit creation flow requires Associate Roles to exist before you can add Associates to a Business Unit. When you set up a Business Unit end to end, plan to create Associate Roles (covered in Module 2) before completing the Business Unit's associate assignments.

Key takeaways

  • A Business Unit is either a Company (top level, no parentUnit) or a Division (has a parentUnit referencing a Company or another Division).
  • A Company's storeMode, associateMode, and approvalRuleMode are always Explicit; a Division defaults to inheritance-friendly modes.
  • topLevelUnit is present on every unit and references the root Company; parentUnit is present only on Divisions.
  • Hierarchies can be up to 5 levels deep, with up to 4 000 descendants per top-level unit.
  • Prefer a flat Company unless the buyer needs different assortments, separate order visibility, or distinct legal entities.

Test your knowledge