An Associate Role groups a set of granular permissions and is assigned to an Associate within a Business Unit. Roles are how you control what each buyer can do: view their own carts, place orders, approve other people's orders, manage Associates, and so on.
Role design is not just an access-control task. The roles you define here determine who can request quotes and whose orders trigger approval later, so decisions on this page carry through to Module 6 (quotes) and Module 7 (approvals).
Sellers define every role
commercetools does not ship predefined Associate Roles. As the Seller, you create every role yourself from the permission catalog, using
POST /associate-roles. The platform's single source of truth for what is grantable is the Permission enum.In practice, most B2B implementations converge on a handful of role archetypes. These are roles you define; they are not platform defaults, but they are a useful starting point.
| Role archetype | Typical responsibility | Representative permissions |
|---|---|---|
| Buyer | Builds carts and places their own orders | CreateMyCarts, UpdateMyCarts, CreateMyOrdersFromMyCarts |
| Reviewer | Views the organization's carts and orders without buying | ViewMyCarts, ViewOthersCarts, ViewOthersOrders |
| Supervisor | Acts across other Associates' resources and approves orders | ViewOthersCarts, CreateOrdersFromOthersCarts, UpdateApprovalFlows |
| Business administrator | Manages the Business Unit and its members | UpdateBusinessUnitDetails, AddChildUnits, UpdateAssociates |
A role is created with a unique, immutable
key, an optional name, and a list of permissions.POST /{projectKey}/associate-roles HTTP/1.1
Content-Type: application/json
{
"key": "buyer",
"name": "Buyer",
"permissions": [
"ViewMyCarts",
"CreateMyCarts",
"UpdateMyCarts",
"CreateMyOrdersFromMyCarts"
]
}
Associate Roles do not have to be created through the API. You can also create and manage them in the Merchant Center, which suits teams that configure roles without writing code. A common misconception is that B2B roles and permissions are API-only; the Merchant Center exposes the same configuration.
The permission naming convention
Permission names follow a predictable pattern that makes them easy to reason about: an action, the keyword
My or Others, and a resource type. For example, UpdateMyOrders and ViewOthersCarts.Mypermissions grant access to the Associate's own resources.Otherspermissions grant access to resources that belong to other Associates in the same Business Unit.
A small set of Business Unit permissions do not follow the
My/Others split, because they act on the organization itself rather than on a buyer's resources: AddChildUnits, UpdateAssociates, UpdateBusinessUnitDetails, and UpdateParentUnit.For the complete list of grantable permissions and the canonical naming convention, see the Permission enum and Permission naming convention in the API reference.
Others does not imply My
A key design point: granting an
Others permission does not automatically grant the matching My permission. The two are independent, which is what makes fine-grained B2B workflows possible.For example, an Associate with
CreateMyCarts, ViewOthersCarts, and CreateOrdersFromOthersCarts can build their own carts and place orders from carts that other people built, but cannot necessarily place orders from their own carts unless you also grant CreateMyOrdersFromMyCarts. You combine My and Others permissions deliberately to model exactly the workflow you need.Make roles buyer-assignable or seller-only
Each role has a
buyerAssignable flag, which defaults to true.buyerAssignable: true: a buyer with theUpdateAssociatespermission (typically a business administrator) can assign this role to other Associates from a buyer portal.buyerAssignable: false: the role can only be assigned by the Seller through the general endpoint, never by a buyer.
Set
buyerAssignable: false for sensitive roles you do not want buyers to grant themselves, such as a high-limit approver role. This flag becomes important when you design self-service provisioning on the Associate provisioning patterns page.Separation of duties
B2B procurement governance usually requires that the person who requests a purchase is not the same person who approves it. The platform does not enforce this for you, but the data model strongly implies the pattern: Approval Rules (Module 7) match a requester role against an approver role, so those must be distinct roles for the separation to hold.
Design for this now by keeping requesting permissions and approving permissions in separate roles:
- A buyer (requester) role gets order-creation permissions such as
CreateMyOrdersFromMyCarts. - An approver role gets approval permissions such as
UpdateApprovalFlows, and is deliberately not granted to the people who place orders.
If a single role held both the ability to place an order and the ability to approve it, an associate could approve their own purchase, defeating the control.
Worked example: Pacific Property Group roles
Pacific Property Group is a Company with two Divisions, Residential and Commercial (Module 1). Design its roles so that buying and approving are separated.
- Division buyer:
ViewMyCarts,CreateMyCarts,UpdateMyCarts,CreateMyOrdersFromMyCarts. Assigned to the buyers in each Division so they can build carts and place their own orders. SetbuyerAssignable: true. - Division approver:
ViewOthersOrders,UpdateApprovalFlows. Assigned to the managers who sign off on orders above a threshold. This role is deliberately not given the buyer's order-creation permissions, so an approver cannot place the orders they approve. SetbuyerAssignable: falseso buyers cannot grant approval rights to themselves. - Company administrator:
UpdateBusinessUnitDetails,UpdateAssociates,AddChildUnits. Assigned at the parent Company to staff who manage the organization and its members.
With buying and approving in separate roles, you can later write an Approval Rule (Module 7) whose requester is the buyer role and whose approver is the approver role, and the separation of duties holds automatically.
Key takeaways
- commercetools ships no predefined roles; the Seller defines every Associate Role from the permission catalog, through the API or in the Merchant Center.
- Permission names combine an action, the
MyorOtherskeyword, and a resource type; a few Business Unit permissions act on the organization and have noMy/Otherssplit. Otherspermissions do not imply the matchingMypermissions, which enables fine-grained workflow modeling.buyerAssignablecontrols whether a buyer administrator can assign a role; set it tofalsefor sensitive roles.- Separate requesting and approving permissions into distinct roles so that Approval Rules can enforce separation of duties later.