Business Units and Associates APIs overview

How to work with the APIs for Business Units and Associates.

This page describes rules that apply across the Business Units and Associates APIs. For what Business Units, Associates, Associate Roles, Permissions, and Approval Rules are and how they behave, see the Business Units and Associates overview.

APIs in this topic

Resource	Purpose	Reference
Business Units	Companies and Divisions, their Associates, Stores, and addresses.	Business Units
Business Unit Search	Search Business Units for back-office use.	Business Unit Search
Associate Roles	Groups of Permissions assigned to Associates.	Associate Roles
Associate endpoints	Access B2B resources as an Associate, with Permission checks.	Associate Carts, Associate Quotes, Associate Quote Requests, Associate Orders, Associate Business Units, Associate Shopping Lists
Approval Rules	Conditions and approver tiers for Order approval.	Approval Rules
Approval Flows	The approval process of one Order.	Approval Flows

Data model

B2B resources

A B2B resource has its businessUnit field set.

Associate Roles and Permissions

Associates can be assigned specific roles through an AssociateRoleAssignment, which grants an Associate Role to an Associate within a Business Unit.

Sellers can make roles assignable by Buyers using the buyerAssignable property of an Associate Role.

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 CreateMyCarts Permission alongside ViewOthersCarts and CreateOrdersFromOthersCarts Permissions enables a setup where Buyers can create carts but require approval from others to place an order.

Interact with B2B resources

Through the general endpoints

When accessing resources using the general endpoint, the API has no knowledge of the Associate behind the API call. Therefore, no Associate Role Permissions are validated. As such, the general endpoints are intended for a 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, the API can derive which Associate is behind a given API call using the password flow token. 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 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. This Business Unit is what the Associate's Permissions are checked against. These endpoints are designed specifically for Sellers that want to provide controlled access for their Buyers using the Permissions.

The endpoints do verify the Permissions according to the URL parameters, but they don't validate the URL parameters against the scopes. 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.

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 (for example, My Carts)	`My` Permissions	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	The Customer must be an Associate of the Business Unit.
`associate` endpoints for B2B resources	`My`, `Others` Permissions	The Associate must be a member of the Business Unit.
`associate` endpoints for Business Units	Business Unit Permissions	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. 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, 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, the API performs validations on certain actions to ensure that the Associate has the correct Business Unit Permissions.

Permission	Required for
`AddChildUnits`	Creating and assigning a new child unit to a parent unit.
`UpdateAssociates`	changeAssociate, removeAssociate update actions, and creating an Associate for a BusinessUnit.
`UpdateParentUnit`	changeParentUnit update action.
`UpdateBusinessUnitDetails`	Update actions not related to Associate management, or hierarchical changes (such as changeParentUnit).

My Carts

For B2B Carts, the My Carts endpoints perform validations to ensure that the Associate has the correct CartPermissions.

Permission	Required for
`CreateMyCarts`	Creating a Cart.
`UpdateMyCarts`	Updating a Cart.
`DeleteMyCarts`	Deleting a Cart.

Additionally, the Customer on the Cart must be an Associate of the referenced Business Unit.

My Quotes

For B2B Quotes, the My Quotes endpoints perform validations to ensure that the Associate has the correct QuotePermissions.

Permission	Required for
`AcceptMyQuotes`	Accepting a Quote.
`DeclineMyQuotes`	Declining a Quote.
`RenegotiateMyQuotes`	Renegotiating a Quote.

My Quote Requests

For B2B Quote Requests, the My Quote Requests endpoints perform validations to ensure that the Associate has the correct QuoteRequestPermissions.

Permission	Required for
`CreateMyQuoteRequestsFromMyCarts`	Creating a Quote Request.
`UpdateMyQuoteRequests`	Updating a Quote Request.

My Orders

For B2B Orders, the My Orders endpoints perform validations to ensure that the Associate has the correct OrderPermissions.

Permission	Required for
`CreateMyOrdersFromMyCarts`	Creating an Order from a Cart and Creating an Order in Store from a Cart.
`CreateMyOrdersFromMyQuotes`	Creating an Order from a Quote.

On the associate endpoints

The associate endpoints validate that the acting Associate has sufficient Permissions on a given resource. In addition, the Associate must have access to the referenced Business Unit. 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 perform validations to ensure that the Associate has the correct Cart Permissions.

Permission	Required for
`ViewMyCarts` or `ViewOthersCarts`	Getting a Cart.
`CreateMyCarts` or `CreateOthersCarts`	Creating a Cart.
`UpdateMyCarts` or `UpdateOthersCarts`	Updating a Cart.
`DeleteMyCarts` or `DeleteOthersCarts`	Deleting a Cart.

Associate Quotes

For B2B Quotes, the Associate Quotes endpoints perform validations to ensure that the Associate has the correct Quote Permissions.

Permission	Required for
`ViewMyQuotes` or `ViewOthersQuotes`	Getting a Quote.
`AcceptMyQuotes` or `AcceptOthersQuotes`	Accepting a Quote.
`DeclineMyQuotes` or `DeclineOthersQuotes`	Declining a Quote.
`RenegotiateMyQuotes` or `RenegotiateOthersQuotes`	Renegotiate a Quote.
`ReassignMyQuotes` or `ReassignOthersQuotes`	Reassigning a Quote.

Associate Quote Requests

For B2B Quote Requests, the Associate Quote Requests endpoints perform validations to ensure that the Associate has the correct Quote Request Permissions.

Permission	Required for
`ViewMyQuoteRequests` or `ViewOthersQuoteRequests`	Getting a Quote Request.
`CreateMyQuoteRequestsFromMyCarts` or `CreateQuoteRequestsFromOthersCarts`	Creating a Quote Request.
`UpdateMyQuoteRequests` or `UpdateOthersQuoteRequests`	Updating a Quote Request.

Associate Orders

For B2B Orders, the Associate Orders endpoints perform validations to ensure that the Associate has the correct Order Permissions.

Permission	Required for
`ViewMyOrders` or `ViewOthersOrders`	Getting an Order.
`CreateMyOrders` or `CreateOthersOrders`	Creating an Order.
`UpdateMyOrders` or `UpdateOthersOrders`	Updating an Order.

Associate Business Units

The Associate Business Unit endpoints perform validations to ensure that the Associate has the correct Business Unit Permissions.

Permission	Required for
`AddChildUnits`	Creating and assigning a new child unit to a parent unit.
`UpdateAssociates`	addAssociate, setAssociates, changeAssociate, and removeAssociate update actions.
`UpdateParentUnit`	changeParentUnit update action.
`UpdateBusinessUnitDetails`	Update actions not related to Associate management, or hierarchical changes (such as changeParentUnit).

Associate Shopping Lists

For B2B Shopping Lists, the Associate Shopping Lists endpoints perform validations to ensure that the Associate has the correct Shopping List Permissions.

Permission	Required for
`ViewMyShoppingLists` or `ViewOthersShoppingLists`	Getting a Shopping List.
`CreateMyShoppingLists` or `CreateOthersShoppingLists`	Creating a Shopping List.
`UpdateMyShoppingLists` or `UpdateOthersShoppingLists`	Updating a Shopping List.
`DeleteMyShoppingLists` or `DeleteOthersShoppingLists`	Deleting a Shopping List.

Inheritance of Associates and their roles

The inheritance behavior is determined by the inheritance property of individual AssociateRoleAssignments together with the AssociateMode 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 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.

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 determines inheritance.

Buyer Approval Flows

The Approval Rules and Approval Flows APIs are designed to be called from a Buyer portal.

Approver hierarchy

An Approval Rule is made of at least one tier in the ApproverHierarchy. Each tier must be composed of at least one ApproverConjunction that contains at least one ApproverDisjunction holding the RuleApprovers. An ApproverConjunction is a condition with the logical operator AND: all of its ApproverDisjunctions must be met. An ApproverDisjunction is a condition with the logical operator OR: any one of its RuleApprovers can approve. For what the AND and OR conditions mean in the approval process, see Business Units and Associates overview.

Working with the APIs

Customer-specific prices B2B B2X

When placing an Order, the Cart's customerId has to reference an Associate in the Business Unit that represents the customer. To ensure that you apply the correct pricing, reference the customer-specific Channel in the distributionChannel of the Cart's Line Item Drafts. Without specifying the Channel, the base price is selected instead of the customer-specific price.

To use Standalone Prices, set the ProductPriceMode to Standalone and create Prices for every Channel.

Creating a Store and Channel per price band is not recommended for checkout flows that use the My Carts and My Orders APIs. It allows the Customer to select the Channel and, therefore, the pricing option for their Orders. Instead, create one Store for each product restriction and price combination. External prices and taxes are not supported with those APIs.

Eventual consistency

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, changes in inherited roles might have a delayed effect on role evaluations.

Limits

Business Units can be organized hierarchically up to a maximum of 5 levels, with the top level being a Business Unit of type Company. Each top-level Business Unit can have a maximum of 4 000 Divisions, including all direct and indirect children. These are soft limits that can be increased per Project after a performance impact review. See Limit increase guidance.

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.

Business Units and Associates APIs overview

APIs in this topic.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

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

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

Permission Naming Convention.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Distinct 'My' and 'Others' Permissions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Interact with B2B resources.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Through the general endpoints.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Through the me endpoint.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Through the associate endpoint.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

On the me endpoints.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

My Business Unit.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

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

My Quote Requests.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

On the associate endpoints.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

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

Associate Quote Requests.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

Associate Business Units.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Associate Shopping Lists.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Inheritance of Associates and their roles.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Conditions for inheritance.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

Buyer Approval Flows.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

Working with the APIs.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Customer-specific prices B2B B2X.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

Eventual consistency of inherited Associates.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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