# Associates overview Overview of the concepts related to Associates, Associate Roles, and Permissions. An [Associate](https://docs.commercetools.com/api/associates-overview.md#associate) is a [Customer](https://docs.commercetools.com/api/projects/customers.md) acting on behalf of a company. Business Units allow you to model companies in hierarchical structures and define which Associates can represent a company. Each Associate in a Business Unit has a specific set of [roles](https://docs.commercetools.com/api/associates-overview.md#associate-role) that determines the [Permissions](https://docs.commercetools.com/api/associates-overview.md#permission) they have. ## Definitions #### Seller In a B2B context, a Seller is a merchant offering goods and services to companies. #### Buyer A Buyer is a company or a representative of the company purchasing goods and services from a [Seller](https://docs.commercetools.com/api/associates-overview.md#seller). They are represented by [Associates](https://docs.commercetools.com/api/projects/business-units.md#associate) in [Business Units](https://docs.commercetools.com/api/projects/business-units.md#businessunit). #### Business Unit A Business Unit represents a [Buyers](https://docs.commercetools.com/api/associates-overview.md#buyer) organization. It can be used to model companies in hierarchical structures and determine which [Associates](https://docs.commercetools.com/api/projects/business-units.md#associate) can act on behalf of the company. #### Associate An [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) is a Customer who represents a company. They have specific roles that determine their permissions to access and perform actions, like creating carts or placing orders. #### Associate Role An [Associate Role](https://docs.commercetools.com/api/projects/associate-roles.md#associaterole) is created and managed by [Sellers](https://docs.commercetools.com/api/associates-overview.md#seller) and defines the granular [Permissions](https://docs.commercetools.com/api/associates-overview.md#permission) associated with each role. It is assigned to an Associate in a Business Unit through an [AssociateRoleAssignment](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociateRoleAssignment). Associates and their roles can be inherited within the hierarchy of Business Units. #### B2B resources Carts, Orders, Recurring Orders, Quotes, Quote Requests, and Shopping Lists that exist within the context of a Business Unit. In practice, this means the resource has its `businessUnit` field set. #### Permission [Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission) provide controlled access to [B2B resources](https://docs.commercetools.com/api/associates-overview.md#b2b-resources), and their naming convention represents the action allowed for a given resource type, for example, `CreateMyCarts`. #### Inheritance Inheritance refers to the process by which [Associates](https://docs.commercetools.com/api/projects/business-units.md#associate) and their roles are passed down within the hierarchy of Business Units. #### Approval Rule An [Approval Rule](https://docs.commercetools.com/api/projects/approval-rules.md#approvalrule) outlines the conditions under which an [Order](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AOrder) that matches a [predicate](https://docs.commercetools.com/api/predicates/predicate-operators.md) needs approval from an approver before it can be ordered by a requester within a [Business Unit](https://docs.commercetools.com/api/associates-overview.md#business-unit). #### Approval Flow An Approval Flow matches [Approval Rules](https://docs.commercetools.com/api/associates-overview.md#approval-rule) to [Orders](https://docs.commercetools.com/api/projects/orders.md#order) and manages the approval state. This includes information about whether the Order is approved or not and the approval status of each approver. #### Buyer portal A Buyer portal is a frontend interface hosted and implemented by the [Seller](https://docs.commercetools.com/api/associates-overview.md#seller). It is used by the [Associates](https://docs.commercetools.com/api/associates-overview.md#associate) of a [Buyer](https://docs.commercetools.com/api/associates-overview.md#buyer) company to manage their [B2B resources](https://docs.commercetools.com/api/associates-overview.md#b2b-resources), [Permissions](https://docs.commercetools.com/api/associates-overview.md#permission), and [Approval Rules](https://docs.commercetools.com/api/associates-overview.md#approval-rule). ```mermaid graph TD subgraph commercetools commerce API platform coco{commercetools commerce
APIs} end subgraph Seller company portal{Buyer portal
frontend + backend} end subgraph Buyer company associate{{Associate}} end associate--uses Buyer portal via web browser
to use B2B features like Buyer Approval Flow-->portal portal--uses commercetools commerce API on behalf of the Associate-->coco ``` ## Associate Roles and Permissions Associates can be assigned specific roles through an [AssociateRoleAssignment](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociateRoleAssignment), which grants an Associate Role to an Associate within a Business Unit. Each Associate Role includes a set of Permissions that provide controlled access to [B2B resources](https://docs.commercetools.com/api/associates-overview.md#b2b-resources). The following diagram shows three example Associate Roles, each with a set of Permissions. ```mermaid graph LR A[Buyer Role] --> B(ViewMyCart) A --> C(CreateMyCart) G[Supervisor Role] --> H(ViewOthersCart) G --> I(CreateOrdersFromOthersQuotes) D[Business Admin Role] --> E(UpdateBusinessUnitDetails) D --> F(AddChildUnits) D --> J(UpdateAssociates) style A fill:#eeeee4 style D fill:#eeeee4 style G fill:#eeeee4 ``` ### Sellers' Role in Managing Permissions [Sellers](https://docs.commercetools.com/api/associates-overview.md#seller) create and manage Associate Roles, including defining the granular Permissions associated with each role. They can make roles assignable by [Buyers](https://docs.commercetools.com/api/associates-overview.md#buyer) using the `buyerAssignable` property of an [Associate Role](https://docs.commercetools.com/api/projects/associate-roles.md#associaterole). ### Permission Naming Convention The naming convention for Permissions represents the action allowed for a given resource type. Most Permission names consist of the action name, either the `My` or `Others` keyword and the resource type (for example, `UpdateMyOrders`, `ViewOthersCarts`). Permissions with the `My` keyword grant access to an Associate's own resources, while `Others` Permissions provide access to resources belonging to other Associates. ### Distinct 'My' and 'Others' Permissions `Others` Permissions don't imply `My` Permissions. This behavior allows for maximum flexibility in modeling complex B2B use cases. For instance, granting an Associate the `CreateMyCart` Permission alongside `ViewOthersCarts` and `CreateOrdersFromOthersCarts` Permissions enables a setup where [Buyers](https://docs.commercetools.com/api/associates-overview.md#buyer) can create carts but require approval from others to place an order. ## Interact with B2B resources The API provides three different ways to access [B2B resources](https://docs.commercetools.com/api/associates-overview.md#b2b-resources): - Using the general endpoints, such as `/{projectKey}/carts`. - Using the [me endpoints](https://docs.commercetools.com/api/me-endpoints-overview.md), such as `/{projectKey}/me/carts`. - Using the `associate` endpoints, such as `/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/carts`. ### Through the general endpoints When accessing resources using the general endpoint, the API has no knowledge of the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) behind the API call. Therefore, no Associate Role Permissions are validated. As such, the general endpoints are intended for a [Seller](https://docs.commercetools.com/api/associates-overview.md#seller) that wants to manage access and permissions without Associate Role enforcement. Example use case: back office operations, customer support. ### Through the me endpoint When using the [me endpoints](https://docs.commercetools.com/api/me-endpoints-overview.md), the API can derive which Associate is behind a given API call using the [password flow token](https://docs.commercetools.com/api/authorization.md#password-flow). This allows the API to check whether the Associate has the right level of Permissions to perform actions on a given resource. However, the `me` endpoint can only grant access to the Associate's own resources, and not to resources that belong to other Associates. Example use case: mobile app for [Buyers](https://docs.commercetools.com/api/associates-overview.md#buyer) to make purchases. ### Through the associate endpoint The `associate` endpoints require an Associate to be specified as a URL parameter along with a [Business Unit](https://docs.commercetools.com/api/projects/business-units.md#businessunit). This Business Unit is what the Associate's [Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission) are checked against. These endpoints are designed specifically for [Sellers](https://docs.commercetools.com/api/associates-overview.md#seller) that want to provide controlled access for their [Buyers](https://docs.commercetools.com/api/associates-overview.md#buyer) using the Permissions. The endpoints do verify the [Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission) according to the URL parameters, but they don't validate the URL parameters against the [scopes](https://docs.commercetools.com/api/scopes.md). Because of this, these endpoints should only be called from a middleware that's trusted. Example use case: B2B storefront using trusted middleware. ## Permission evaluation Permission evaluations and requirements differ based on the endpoint type. The following table provides an overview of the types of Permissions required depending on which method is used to access a resource. (a CSV formatted table follows. The first line are the column names.) Endpoint type,Permission evaluation,Additional requirements General endpoints,None,If `customerId` and `businessUnit` are both present on the resource, then the Customer must be an Associate of the Business Unit. `me` endpoints for [B2B resources](https://docs.commercetools.com/api/associates-overview.md#b2b-resources) (for example, My Carts),`My` [Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission),If `customerId` and `businessUnit` are both present on the resource, then the Customer must be an Associate of the Business Unit. `me` endpoints for Business Units (My Business Units),[Business Unit Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission),The Customer must be an Associate of the Business Unit. `associate` endpoints for [B2B resources](https://docs.commercetools.com/api/associates-overview.md#b2b-resources),`My`, `Others` [Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission),The Associate must be a member of the Business Unit. `associate` endpoints for Business Units,[Business Unit Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission),The Associate must be a member of the Business Unit. ### On the me endpoints The `me` endpoints validate that the acting Associate has sufficient Permissions on a given [B2B resources](https://docs.commercetools.com/api/associates-overview.md#b2b-resources). In addition, the Associate must be a Customer on the resource and be an Associate of the referenced Business Unit. The `me` endpoints do not validate `View` Permissions. Therefore, an Associate can view all resources available on the [me endpoints](https://docs.commercetools.com/api/me-endpoints-overview.md), regardless of their Permissions. Removing an Associate from a Business Unit does not revoke their access to the Carts, Orders, Quotes, and Quote Requests associated with it. The Associate must also be explicitly removed from the entity to fully restrict their access. #### My Business Unit When interacting with Business Units using the [My Business Unit endpoints](https://docs.commercetools.com/api/projects/me-business-units.md), the API performs validations on certain actions to ensure that the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has the correct [Business Unit Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission). (a CSV formatted table follows. The first line are the column names.) Permission,Required for `AddChildUnits`,[Creating and assigning a new child unit to a parent unit](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fme%2Fbusiness-units%3APOST). `UpdateAssociates`,[changeAssociate](https://docs.commercetools.com/api/projects/me-business-units.md#change-associate), [removeAssociate](https://docs.commercetools.com/api/projects/me-business-units.md#remove-associate) update actions, and [creating an Associate for a BusinessUnit](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fme%2Fcustomers%3APOST). `UpdateParentUnit`,[changeParentUnit](https://docs.commercetools.com/api/projects/me-business-units.md#change-parent-unit) update action. `UpdateBusinessUnitDetails`,[Update actions](https://docs.commercetools.com/api/projects/me-business-units.md#update-actions) not related to Associate management, or hierarchical changes (such as [changeParentUnit](https://docs.commercetools.com/api/projects/me-business-units.md#change-parent-unit)). #### My Carts For B2B Carts, the [My Carts endpoints](https://docs.commercetools.com/api/projects/me-carts.md) perform validations to ensure that the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has the correct [CartPermissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission). (a CSV formatted table follows. The first line are the column names.) Permission,Required for `CreateMyCarts`,[Creating a Cart](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fme%2Fcarts%3APOST). `UpdateMyCarts`,[Updating a Cart](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fme%2Fcarts%2F%7Bid%7D%3APOST). `DeleteMyCarts`,[Deleting a Cart](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fme%2Fcarts%2F%7Bid%7D%3ADELETE). Additionally, the Customer on the Cart must be an [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) of the referenced [Business Unit](https://docs.commercetools.com/api/projects/business-units.md#businessunit). #### My Quotes For B2B Quotes, the [My Quotes endpoints](https://docs.commercetools.com/api/projects/me-quotes.md) perform validations to ensure that the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has the correct [QuotePermissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission). (a CSV formatted table follows. The first line are the column names.) Permission,Required for `AcceptMyQuotes`,[Accepting a Quote](https://docs.commercetools.com/api/projects/me-quotes.md#change-my-quote-state). `DeclineMyQuotes`,[Declining a Quote](https://docs.commercetools.com/api/projects/me-quotes.md#change-my-quote-state). `RenegotiateMyQuotes`,[Renegotiating a Quote](https://docs.commercetools.com/api/projects/me-quotes.md#request-quote-renegotiation). #### My Quote Requests For B2B Quote Requests, the [My Quote Requests endpoints](https://docs.commercetools.com/api/projects/me-quote-requests.md) perform validations to ensure that the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has the correct [QuoteRequestPermissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission). (a CSV formatted table follows. The first line are the column names.) Permission,Required for `CreateMyQuoteRequestsFromMyCarts`,[Creating a Quote Request](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fme%2Fquote-requests%3APOST). `UpdateMyQuoteRequests`,[Updating a Quote Request](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fme%2Fquote-requests%2F%7Bid%7D%3APOST). #### My Orders For B2B Orders, the [My Orders endpoints](https://docs.commercetools.com/api/projects/me-orders.md) perform validations to ensure that the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has the correct [OrderPermissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission). (a CSV formatted table follows. The first line are the column names.) Permission,Required for `CreateMyOrdersFromMyCarts`,[Creating an Order from a Cart](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fme%2Forders%3APOST) and [Creating an Order in Store from a Cart](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fin-store%2Fkey%3D%7BstoreKey%7D%2Fme%2Forders%3APOST). `CreateMyOrdersFromMyQuotes`,[Creating an Order from a Quote](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fme%2Forders%2Fquotes%3APOST). ### On the associate endpoints The `associate` endpoints validate that the acting [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has sufficient Permissions on a given resource. In addition, the Associate must have access to the referenced [Business Unit](https://docs.commercetools.com/api/projects/business-units.md#businessunit). In contrast to the `me` endpoints, the `associate` endpoints can also provide access to resources that do not belong to the Associate directly. For example, the `ViewOthersCarts` Permission allows an Associate to view B2B Carts where the Customer on the Cart is another Associate. #### Associate Carts For B2B Carts, the [Associate Carts endpoints](https://docs.commercetools.com/api/projects/associate-carts.md) perform validations to ensure that the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has the correct [Cart Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission). (a CSV formatted table follows. The first line are the column names.) Permission,Required for `ViewMyCarts` or `ViewOthersCarts`,[Getting a Cart](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fcarts%2F%7Bid%7D%3AGET). `CreateMyCarts` or `CreateOthersCarts`,[Creating a Cart](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fcarts%3APOST). `UpdateMyCarts` or `UpdateOthersCarts`,[Updating a Cart](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fcarts%2F%7Bid%7D%3APOST). `DeleteMyCarts` or `DeleteOthersCarts`,[Deleting a Cart](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fcarts%2F%7Bid%7D%3ADELETE). #### Associate Quotes For B2B Quotes, the [Associate Quotes endpoints](https://docs.commercetools.com/api/projects/associate-quotes.md) perform validations to ensure that the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has the correct [Quote Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission). (a CSV formatted table follows. The first line are the column names.) Permission,Required for `ViewMyQuotes` or `ViewOthersQuotes`,[Getting a Quote](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fquotes%2F%7Bid%7D%3AGET). `AcceptMyQuotes` or `AcceptOthersQuotes`,[Accepting a Quote](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fquotes%2F%7Bid%7D%3APOST). `DeclineMyQuotes` or `DeclineOthersQuotes`,[Declining a Quote](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fquotes%2F%7Bid%7D%3APOST). `RenegotiateMyQuotes` or `RenegotiateOthersQuotes`,[Renegotiate a Quote](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fquotes%2F%7Bid%7D%3APOST). `ReassignMyQuotes` or `ReassignOthersQuotes`,[Reassigning a Quote](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fquotes%2F%7Bid%7D%3APOST). #### Associate Quote Requests For B2B Quote Requests, the [Associate Quote Requests endpoints](https://docs.commercetools.com/api/projects/associate-quote-requests.md) perform validations to ensure that the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has the correct [Quote Request Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission). (a CSV formatted table follows. The first line are the column names.) Permission,Required for `ViewMyQuoteRequests` or `ViewOthersQuoteRequests`,[Getting a Quote Request](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fquote-requests%2F%7Bid%7D%3AGET). `CreateMyQuoteRequestsFromMyCarts` or `CreateQuoteRequestsFromOthersCarts`,[Creating a Quote Request](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fquote-requests%3APOST). `UpdateMyQuoteRequests` or `UpdateOthersQuoteRequests`,[Updating a Quote Request](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fquote-requests%2F%7Bid%7D%3APOST). #### Associate Orders For B2B Orders, the [Associate Orders endpoints](https://docs.commercetools.com/api/projects/associate-orders.md) perform validations to ensure that the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has the correct [Order Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission). (a CSV formatted table follows. The first line are the column names.) Permission,Required for `ViewMyOrders` or `ViewOthersOrders`,[Getting an Order](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Forders%2F%7Bid%7D%3AGET). `CreateMyOrders` or `CreateOthersOrders`,[Creating an Order](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Forders%3APOST). `UpdateMyOrders` or `UpdateOthersOrders`,[Updating an Order](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Forders%2F%7Bid%7D%3APOST). #### Associate Business Units The [Associate Business Unit endpoints](https://docs.commercetools.com/api/projects/associate-business-units.md) perform validations to ensure that the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has the correct [Business Unit Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission). (a CSV formatted table follows. The first line are the column names.) Permission,Required for `AddChildUnits`,[Creating and assigning a new child unit to a parent unit](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fbusiness-units%3APOST). `UpdateAssociates`,[addAssociate](https://docs.commercetools.com/api/projects/business-units.md#add-associate), [setAssociates](https://docs.commercetools.com/api/projects/business-units.md#set-associates), [changeAssociate](https://docs.commercetools.com/api/projects/business-units.md#change-associate), and [removeAssociate](https://docs.commercetools.com/api/projects/business-units.md#remove-associate) update actions. `UpdateParentUnit`,[changeParentUnit](https://docs.commercetools.com/api/projects/business-units.md#change-parent-unit) update action. `UpdateBusinessUnitDetails`,[Update actions](https://docs.commercetools.com/api/projects/business-units.md#update-actions) not related to Associate management, or hierarchical changes (such as [changeParentUnit](https://docs.commercetools.com/api/projects/business-units.md#change-parent-unit)). #### Associate Shopping Lists For B2B Shopping Lists, the [Associate Shopping Lists endpoints](https://docs.commercetools.com/api/projects/associate-shopping-lists.md) perform validations to ensure that the [Associate](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociate) has the correct [Shopping List Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission). (a CSV formatted table follows. The first line are the column names.) Permission,Required for `ViewMyShoppingLists` or `ViewOthersShoppingLists`,[Getting a Shopping List](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fshopping-lists%2F%7Bid%7D%3AGET). `CreateMyShoppingLists` or `CreateOthersShoppingLists`,[Creating a Shopping List](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fshopping-lists%3APOST). `UpdateMyShoppingLists` or `UpdateOthersShoppingLists`,[Updating a Shopping List](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fshopping-lists%2F%7Bid%7D%3APOST). `DeleteMyShoppingLists` or `DeleteOthersShoppingLists`,[Deleting a Shopping List](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fas-associate%2F%7BassociateId%7D%2Fin-business-unit%2Fkey%3D%7BbusinessUnitKey%7D%2Fshopping-lists%2F%7Bid%7D%3ADELETE). ## Inheritance of Associates and their roles Associates and their roles can be inherited within the [hierarchy of Business Units](https://docs.commercetools.com/api/customers-overview.md#hierarchies-within-business-units). The inheritance behavior is determined by the `inheritance` property of individual [AssociateRoleAssignments](https://docs.commercetools.com/api/projects/business-units.md#associateroleassignment) together with the [AssociateMode](https://docs.commercetools.com/api/projects/business-units.md#businessunitassociatemode) of a Business Unit. ### Conditions for inheritance When the AssociateMode of a Business Unit is set to `Explicit`, the Business Unit is not allowed to inherit any Associates. In this case, only Associates defined directly on the Business Unit can act on its behalf. With the `ExplicitAndFromParent` AssociateMode, the Business Unit can have both directly assigned Associates and inherited ones from a parent unit. For a Business Unit to inherit Associates from a parent unit, the following two conditions must be met: - The AssociateMode of the Business Unit must be set to `ExplicitAndFromParent`, allowing the Business Unit to inherit Associates. - A parent unit of the Business Unit must have at least one Associate with an inheritable role, meaning that the `inheritance` property of the [AssociateRoleAssignment](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociateRoleAssignment) is set to `Enabled`. The following diagram illustrates how Business Units with `ExplicitAndFromParent` AssociateMode inherit Associates from parents, whilst a Business Unit with \`\`Explicit\` AssociateMode does not. ```mermaid flowchart TB classDef default fill:#e6f5fe,stroke:#078cdf,stroke-width:1px,color:#000000; classDef note fill:#e6f5fe,stroke:#078cdf,stroke-width:1px,color:#000000,stroke-dasharray: 5 5; subgraph Company direction LR subgraph explicit1[Explicit] direction TB companyAssociate1(Associate 1) end end subgraph BusinessUnitChildExplicit[Division] direction LR noteExplicit(associateMode: Explicit) subgraph explicit2[Explicit] direction TB divisionExplicitAssociate2(Associate 2) divisionExplicitAssociate4(Associate 4) end end subgraph BusinessUnitChildExplicitAndFromParent[Division] direction LR noteExplicitAndFromParent(associateMode: ExplicitAndFromParent) subgraph inherited3[Inherited] direction TB divisionExplicitAndFromParentAssociate1(Associate 1) end subgraph explicit3[Explicit] direction TB divisionExplicitAndFromParentAssociate2(Associate 2) end end subgraph BusinessUnitChildSubDivision[Division] direction LR noteExplicitAndFromParent2(associateMode: ExplicitAndFromParent) subgraph inherited4[Inherited] direction TB subdivisionExplicitAndFromParentAssociate1(Associate 1) subdivisionExplicitAndFromParentAssociate2(Associate 2) end subgraph explicit4[Explicit] direction TB subdivisionExplicitAndFromParentAssociate3(Associate 3) end end Company --> BusinessUnitChildExplicit Company --> BusinessUnitChildExplicitAndFromParent BusinessUnitChildExplicitAndFromParent --> BusinessUnitChildSubDivision class noteExplicitAndFromParent,noteExplicitAndFromParent2,noteExplicit note ``` ### Eventual consistency of inherited Associates The `inheritedAssociates` array of a Business Unit contains the Associates that are inherited. In cases where inheritance applies, this property is automatically populated by a background task. It is updated each time an Associate in a parent Business Unit is added, updated, or removed. However, since this process is subject to [eventual consistency](https://docs.commercetools.com/api/general-concepts.md#eventual-consistency), changes in inherited roles might have a delayed effect on role evaluations. ### Accumulative permissions of inherited roles The [Permissions](https://docs.commercetools.com/api/projects/associate-roles.md#permission) of an Associate are the sum of all permissions included on the Associate Role assigned to the Associate directly, and those from inherited roles. The following example demonstrates how permissions accumulate. ```mermaid flowchart LR classDef default fill:#e6f5fe,stroke:#078cdf,stroke-width:1px,color:#000000; classDef group fill:#e6f5fe,stroke-width:0px; subgraph Associate[Associate in a Business Unit] direction LR subgraph Inherited[Inherited Roles] direction LR Role1 --> ViewMyCarts([ViewMyCarts]) Role1 --> ViewOthersCarts([ViewOthersCarts]) direction LR Role2 --> ViewMyOrders([ViewMyOrders]) Role2 --> ViewOthersOrders([ViewOthersOrders]) end subgraph Explicit[Explicit Roles] direction LR Role3 --> ViewMyQuotes([ViewMyQuotes]) Role3 --> ViewOthersQuotes([ViewOthersQuotes]) end subgraph AssociatePermissions[Resulting permissions] note(Role1 + Role2 + Role3) direction LR subgraph ViewCarts[ ] direction TB ViewMyCartsR([ViewMyCarts]) ViewOthersCartsR([ViewOthersCarts]) end subgraph ViewOrders[ ] ViewMyOrdersR([ViewMyOrders]) ViewOthersOrdersR([ViewOthersOrders]) end subgraph ViewQuotes[ ] ViewMyQuotesR([ViewMyQuotes]) ViewOthersQuotesR([ViewOthersQuotes]) end end end Inherited -.-> AssociatePermissions Explicit -.-> AssociatePermissions style AssociatePermissions stroke-dasharray: 5 5 class ViewCarts,ViewOrders,ViewQuotes group ``` ### Prevent inheritance By setting the AssociateMode of a Business Unit to `Explicit`, the inheritance mechanism will be disabled for all Associates of that unit. To prevent the inheritance of a single Associate, disable the inheritance property for all assigned roles of that Associate. This ensures that the Associate is not inherited by any child Business Units. If an Associate is both inherited and explicitly defined in the same Associate Role, the explicitly defined [AssociateRoleAssignment](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AAssociateRoleAssignment) determines inheritance. ## Buyer Approval Flows Buyer Approval Flows provide a flexible [Order](https://docs.commercetools.com/api/projects/orders.md) approval process for [Business Units](https://docs.commercetools.com/api/associates-overview.md#business-unit). They define conditions that necessitate the requirement for an Order to be approved. This mechanism is useful especially when structuring multi-tiered approval processes for B2B ordering processes. [Approval Flows](https://docs.commercetools.com/api/associates-overview.md#approval-flow) are linked to Orders and are initiated by matching [Approval Rules](https://docs.commercetools.com/api/associates-overview.md#approval-rule). The Approval Rule encapsulates the conditions an Order must meet to qualify for the rule's approval process. Approval Rules consist of one or more levels, that are referred to as tiers within an [approver hierarchy](https://docs.commercetools.com/api/projects/approval-rules.md#approverhierarchy). Each tier encapsulates one or more [Associate Roles](https://docs.commercetools.com/api/associates-overview.md#associate-role) that must authorize the Order before it advances to the subsequent tier. These APIs are designed to be called from a [Buyer portal](https://docs.commercetools.com/api/associates-overview.md#buyer-portal). ### Intended workflow Approval Flows represent the [Order](https://docs.commercetools.com/api/projects/orders.md) approval process. For Approval Flows to come into effect, Buyers are required to [configure Approval Rules](https://docs.commercetools.com/api/associates-overview.md#configure-approval-rules) as per their organizational requirements. The following steps describe the intended workflow, alongside a corresponding diagram: 1. A Requester creates a new Order. 2. The API checks whether any Approval Rules match the Order. 1. If the Order matches one or more Approval Rules: 1. A new Approval Flow is initiated in a `Pending` state to track the approval process. 2. Approvers provide their approvals or rejections, conforming to the specified tier hierarchy. 3. If all required Approvers provide approval, the Approval Flow's status changes to `Approved`. 4. If any rejections occur, the Approval Flow's status changes to `Rejected`. 2. If the Order doesn't match any Approval Rules, it bypasses the approval process. When an Approval Flow's status changes to `Approved` or `Rejected`, it signifies the completion of the approval process. Image url: https://docs.commercetools.com/api/images/buyer-approval-flows/approval-workflow\.png Alt text: A diagram showing the approval workflow steps ### Configure Approval Rules [Approval Rules](https://docs.commercetools.com/api/associates-overview.md#approval-rule) provide a flexible approach to defining approval requirements for [Orders](https://docs.commercetools.com/api/projects/orders.md) using boolean logic. Approvers are designated by [Associate Roles](https://docs.commercetools.com/api/associates-overview.md#associate-role), preventing the need to bind Approval Rules to specific individuals. The configuration supports multiple tiers of approver expressions, allowing for the next level of approvers to be notified only when the preceding level has approved the Order. To streamline the approval process, higher-level approvers also have the option to approve an Order before they receive a notification. This early approval automatically approves all lower levels. An Approval Rule is made of at least one tier in the [ApproverHierarchy](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AApproverHierarchy). Each tier must be composed of at least one [ApproverConjunction](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AApproverConjunction) that contains at least one [ApproverDisjunction](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AApproverDisjunction) holding the [RuleApprovers](https://docs.commercetools.com/api/projects/approval-rules.md#ruleapprover). ```mermaid flowchart subgraph tier[ApproverHierarchy Tier 1] direction TB and21[ApproverConjunction] or21[ApproverDisjunction] or21 --> role21[RuleApprover] and21 --> or21 end ``` ApproverDisjunction and an ApproverConjunction refer to specific components of logical expressions within an Approval Rule. In an ApproverDisjunction, if any of the conditions is true, the whole expression is true. Applied to the approval process, an ApproverDisjunction represents a scenario where any one of a set of approvers can approve an Order for it to pass. In an ApproverConjunction, all conditions must be true for the whole expression to be true. For the approval process, an ApproverConjunction means that all specified approvers must approve an Order for it to pass. ```mermaid flowchart subgraph tier1[Tier 1] direction TB and11[AND] or11[OR] or12[OR] or11 --> role11[Associate A] or11 --> role12[Associate B] or12 --> role14[Associate C] and11 --> or11 and11 --> or12 end ``` With up to five levels per Approval Rule, an Order can pass through a maximum of five sequential approval stages. Each level corresponds to an approval stage, starting from the initial stage at the first level to the final approval at the fifth level. ```mermaid flowchart subgraph tier1[Tier 1] end subgraph tier2[Tier 2] end subgraph tier3[Tier 3] end subgraph tier4[Tier 4] end subgraph tier5[Tier 5] end tier1 --> tier2 tier2 --> tier3 tier3 --> tier4 tier4 --> tier5 ``` #### Example configuration of an Approval Rule Let's look at an example of an approver hierarchy. In this configuration, for an Order to be fully approved, the following approvers must approve: 1. The Project Team Lead OR their substitute AND the Engineering Manager 2. Head of Procurement 3. CEO The approval process is sequential based on the tiers. In this case, the Head of Procurement won't be required to approve the Order until both the Project Team Lead and Engineering Manager have approved. If either of them doesn't approve the Order, the Head of Procurement and all subsequent tiers (in this case, the CEO) will not have to review it. The following diagram denotes the conjunctions and disjunctions necessary to express this hierarchy. ```mermaid flowchart subgraph tier1[Tier 1] direction TB and11[AND] or11[OR] or12[OR] or11 --> role11[Project Team Lead] or11 --> role12[Project Team Lead substitute] or12 --> role14[Engineering Manager] and11 --> or11 and11 --> or12 end subgraph tier2[Tier 2] direction TB and21[AND] or21[OR] or21 --> role21[Head of Procurement] and21 --> or21 end subgraph tier3[Tier 3] direction TB and31[AND] or31[OR] or31 --> role31[CEO] and31 --> or31 end tier1 --> tier2 tier2 --> tier3 ``` The JSON notation for the same hierarchy can be expressed as follows: ```json { "tiers": [ { "and": [ { "or": [ { "associateRole": { "typeId": "associate-role", "key": "project-team-lead" } }, { "associateRole": { "typeId": "associate-role", "key": "project-team-lead-substitute" } } ] }, { "or": [ { "associateRole": { "typeId": "associate-role", "key": "engineering-manager" } } ] } ] }, { "and": [ { "or": [ { "associateRole": { "typeId": "associate-role", "key": "head-of-procurement" } } ] } ] }, { "and": [ { "or": [ { "associateRole": { "typeId": "associate-role", "key": "ceo" } } ] } ] } ] } ``` ## Related pages - [Section overview page](https://docs.commercetools.com/api.md) - [Next page: Business Units](https://docs.commercetools.com/api/projects/business-units.md)