Queries and mutations for managing Business Units in the platform.

Queries

Query Business Units

QUERYbusinessUnits
Arguments
where​
String​
sort​
Array of String​
limit​
Int​
offset​
Int​

Get Business Unit

QUERYbusinessUnit
Arguments
id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Get Associate in Business Unit

QUERYassociate
Arguments
businessUnitId​
String​

Queries with specified Business Unit ID

businessUnitKey​
String​

Queries with specified Business Unit key

associateId​
String​

Queries the specific associate within the Business Unit

Mutations

To change a Business Unit, updateBusinessUnit takes a list of update actions. For behavior, see Business Units in the HTTP API.

Create Business Unit

MUTATIONcreateBusinessUnit
Arguments
draft​
asAssociate​

Create/modify entity as an associate in business-unit.

storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

Update Business Unit

MUTATIONupdateBusinessUnit
Arguments
version​
Long​
actions​
asAssociate​

Create/modify entity as an associate in business-unit.

storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Delete Business Unit

MUTATIONdeleteBusinessUnit
Arguments
version​
Long​
personalDataErasure​
Boolean​
Default: false​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output types

BusinessUnit

Generic type to model the fields that all types of Business Units have in common.

id​
String​

Unique identifier of the Business Unit.

key​
String​

User-defined unique and immutable identifier of the Business Unit.

name​
String​

Name of the Business Unit.

contactEmail​
String​

Email address of the Business Unit.

addresses​
Array of Address​

Addresses used by the Business Unit.

defaultShippingAddress​
defaultBillingAddress​
defaultShippingAddressId​
String​

Unique identifier of the address used as the default shipping address.

defaultBillingAddressId​
String​

Unique identifier of the address used as the default billing address.

shippingAddresses​
Array of Address​
billingAddresses​
Array of Address​
shippingAddressIds​
Array of String​

Unique identifiers of addresses used as shipping addresses.

billingAddressIds​
Array of String​

Unique identifiers of addresses used as billing addresses.

status​
Indicates whether the Business Unit can be edited and used in Orders.
Can be Active, or Inactive​
storesRef​
Array of KeyReference​
References to Stores the Business Unit is associated with. Only present when storeMode is Explicit.
If the Business Unit has Stores defined, then all of its Carts, Orders, Recurring Orders, Quotes, Quote Requests, or Shopping Lists must belong to one of the Business Unit's Stores.
If the Business Unit has no Stores, then all of its Carts, Orders, Recurring Orders, Quotes, Quote Requests, or Shopping Lists must not belong to any Store.
stores​
Array of Store​
References to Stores the Business Unit is associated with. Only present when storeMode is Explicit.
If the Business Unit has Stores defined, then all of its Carts, Orders, Recurring Orders, Quotes, Quote Requests, or Shopping Lists must belong to one of the Business Unit's Stores.
If the Business Unit has no Stores, then all of its Carts, Orders, Recurring Orders, Quotes, Quote Requests, or Shopping Lists must not belong to any Store.
storeMode​
String​

Defines whether the Stores of the Business Unit are set directly on the Business Unit or are inherited from a parent.

unitType​

Type of the Business Unit indicating its position in a hierarchy.

Can be Company, or Division​
associates​
Array of Associate​
Associates that are part of the Business Unit in specific roles.
associateMode​
Set to Explicit to prevent the Business Unit inheriting Associates from a parent, set to ExplicitAndFromParent to enable inheritance.
Can be Explicit, or ExplicitAndFromParent​
inheritedAssociates​
Array of InheritedAssociate​
Associates that are inherited from a parent Business Unit. The value of this field is eventually consistent and is only present when the associateMode is set to ExplicitAndFromParent.
custom​

Custom Fields of the Business Unit.

parentUnitRef​
Parent unit of the Business Unit. Only present when the unitType is Division.
parentUnit​
Parent unit of the Business Unit. Only present when the unitType is Division.
ancestors​
Array of BusinessUnit​

This field contains the BusinessUnits KeyReferences from the Company to the parent Division of this BusinessUnit in that order.

inheritedStores​
Array of InheritedStore​

This field contains the inherited stores from its parentUnit if storeMode is set to FromParent.

topLevelUnitRef​
Top-level unit of the Business Unit. The top-level unit is of unitType Company.
topLevelUnit​
Top-level unit of the Business Unit. The top-level unit is of unitType Company.
approvalRuleMode​
Determines whether the Business Unit can inherit Approval Rules from a parent. Always Explicit for Companies and defaults to ExplicitAndFromParent for Divisions.
Can be Explicit, or ExplicitAndFromParent​
customerGroupAssignments​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
version​
Long​

Current version of the Business Unit.

createdAt​

Date and time (UTC) the Business Unit was initially created.

lastModifiedAt​

Date and time (UTC) the Business Unit was last updated.

createdBy​

IDs and references that created the BusinessUnit.

lastModifiedBy​

IDs and references that last modified the BusinessUnit.

BusinessUnitStatus

Active
Inactive

BusinessUnitType

Company
Division

Associate

associateRoleAssignments​

Roles assigned to the Associate within a Business Unit.

customerRef​
The Customer that acts as an Associate in the Business Unit.
customer​
The Customer that acts as an Associate in the Business Unit.

AssociateRoleAssignment

associateRoleRef​

Role the Associate holds within a Business Unit.

associateRole​

Role the Associate holds within a Business Unit.

inheritance​

Determines whether the AssociateRoleAssignment can be inherited by child Business Units.

Can be Disabled, or Enabled​

AssociateInheritanceMode

Disabled
Enabled

BusinessUnitAssociateMode

Explicit
ExplicitAndFromParent

InheritedAssociate

associateRoleAssignments​

Inherited roles of the Associate within a Business Unit.

customerRef​
The Customer that acts as an Associate in the Business Unit.
customer​
The Customer that acts as an Associate in the Business Unit.

InheritedAssociateRoleAssignment

associateRoleRef​

Inherited role the Associate holds within a Business Unit.

associateRole​

Inherited role the Associate holds within a Business Unit.

sourceRef​

Reference to the parent Business Unit where the assignment is defined explicitly.

source​

Reference to the parent Business Unit where the assignment is defined explicitly.

InheritedStore

store​
storeRef​

BusinessUnitApprovalRuleMode

Explicit
ExplicitAndFromParent

BusinessUnitQueryResult

offset​
Int​
count​
Int​
total​
Long​
exists​
Boolean​
results​
Array of BusinessUnit​

BusinessUnitAssociateProjection

customerRef​
customer​
associateRoles​
Array of AssociateRole​
inheritedAssociateRoles​
Array of AssociateRole​
permissions​
Array of Permission​
Can be AcceptMyQuotes, AcceptOthersQuotes, AddChildUnits, CreateApprovalRules, CreateMyCarts, CreateMyOrdersFromMyCarts, CreateMyOrdersFromMyQuotes, CreateMyPaymentMethods, CreateMyQuoteRequestsFromMyCarts, CreateMyShoppingLists, CreateOrdersFromOthersCarts, CreateOrdersFromOthersQuotes, CreateOthersCarts, CreateOthersPaymentMethods, CreateOthersShoppingLists, CreateQuoteRequestsFromOthersCarts, DeclineMyQuotes, DeclineOthersQuotes, DeleteMyCarts, DeleteMyPaymentMethods, DeleteMyShoppingLists, DeleteOthersCarts, DeleteOthersPaymentMethods, DeleteOthersShoppingLists, ReassignMyQuotes, ReassignOthersQuotes, RenegotiateMyQuotes, RenegotiateOthersQuotes, UpdateApprovalFlows, UpdateApprovalRules, UpdateAssociates, UpdateBusinessUnitDetails, UpdateMyCarts, UpdateMyOrders, UpdateMyPaymentMethods, UpdateMyQuoteRequests, UpdateMyShoppingLists, UpdateOthersCarts, UpdateOthersOrders, UpdateOthersPaymentMethods, UpdateOthersQuoteRequests, UpdateOthersShoppingLists, UpdateParentUnit, ViewMyCarts, ViewMyOrders, ViewMyPaymentMethods, ViewMyQuoteRequests, ViewMyQuotes, ViewMyShoppingLists, ViewOthersCarts, ViewOthersOrders, ViewOthersPaymentMethods, ViewOthersQuoteRequests, ViewOthersQuotes, or ViewOthersShoppingLists​

Permission

AcceptMyQuotes
AcceptOthersQuotes
AddChildUnits
CreateApprovalRules
CreateMyCarts
CreateMyOrdersFromMyCarts
CreateMyOrdersFromMyQuotes
CreateMyPaymentMethods
CreateMyQuoteRequestsFromMyCarts
CreateMyShoppingLists
CreateOrdersFromOthersCarts
CreateOrdersFromOthersQuotes
CreateOthersCarts
CreateOthersPaymentMethods
CreateOthersShoppingLists
CreateQuoteRequestsFromOthersCarts
DeclineMyQuotes
DeclineOthersQuotes
DeleteMyCarts
DeleteMyPaymentMethods
DeleteMyShoppingLists
DeleteOthersCarts
DeleteOthersPaymentMethods
DeleteOthersShoppingLists
ReassignMyQuotes
ReassignOthersQuotes
RenegotiateMyQuotes
RenegotiateOthersQuotes
UpdateApprovalFlows
UpdateApprovalRules
UpdateAssociates
UpdateBusinessUnitDetails
UpdateMyCarts
UpdateMyOrders
UpdateMyPaymentMethods
UpdateMyQuoteRequests
UpdateMyShoppingLists
UpdateOthersCarts
UpdateOthersOrders
UpdateOthersPaymentMethods
UpdateOthersQuoteRequests
UpdateOthersShoppingLists
UpdateParentUnit
ViewMyCarts
ViewMyOrders
ViewMyPaymentMethods
ViewMyQuoteRequests
ViewMyQuotes
ViewMyShoppingLists
ViewOthersCarts
ViewOthersOrders
ViewOthersPaymentMethods
ViewOthersQuoteRequests
ViewOthersQuotes
ViewOthersShoppingLists

Input types

BusinessUnitDraft

Generic draft type to model those fields all Business Units have in common. The additional fields required for creating a Company or Division are represented on CompanyDraft and DivisionDraft.
key​
String​

User-defined unique and immutable identifier for the Business Unit.

name​
String​

Name of the Business Unit.

contactEmail​
String​

Email address of the Business Unit.

addresses​
Array of AddressInput​

Addresses used by the Business Unit.

defaultBillingAddress​
Int​
The index of the address in the addresses list. The defaultBillingAddressId of the customer will be set to the ID of that address.
defaultShippingAddress​
Int​
The index of the address in the addresses list. The defaultShippingAddressId of the customer will be set to the ID of that address.
shippingAddresses​
Array of Int​
The indices of the shipping addresses in the addresses list. The shippingAddressIds of the Customer will be set to the IDs of that addresses.
Default: []​
billingAddresses​
Array of Int​
The indices of the billing addresses in the addresses list. The billingAddressIds of the customer will be set to the IDs of that addresses.
Default: []​
custom​

Custom Fields for the Business Unit.

unitType​

Type of the Business Unit indicating its position in a hierarchy.

Can be Company, or Division​
storeMode​
String​
Defines whether the Stores of the Business Unit are set directly on the Business Unit or are inherited from a parent. storeMode is always Explicit for Companies and defaults to FromParent for Divisions.
parentUnit​
stores​
Sets the Stores the Business Unit is associated with. Can only be set when storeMode is Explicit. Defaults to empty for Companies and not set for Divisions.
If the Business Unit has Stores defined, then all of its Carts, Orders, Recurring Orders, Quotes, Quote Requests, or Shopping Lists must belong to one of the Business Unit's Stores.
If the Business Unit has no Stores, then all of its Carts, Orders, Recurring Orders, Quotes, Quote Requests, or Shopping Lists must not belong to any Store.
associates​
Array of AssociateDraft​
List of members that are part of the Business Unit in specific roles.
associateMode​
Determines whether the Business Unit can inherit Associates from a parent. Always Explicit for Companies and defaults to ExplicitAndFromParent for Divisions.
Can be Explicit, or ExplicitAndFromParent​
approvalRuleMode​
Determines whether the Business Unit can inherit Approval Rules from a parent. For Companies, the value of this field is always Explicit. For Divisions, the default value is ExplicitAndFromParent.
Can be Explicit, or ExplicitAndFromParent​
customerGroupAssignments​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta

BusinessUnitType

Company
Division

AssociateDraft

The Customer to be part of the Business Unit.
associateRoleAssignments​

Roles assigned to the Associate within a Business Unit.

AssociateRoleAssignmentDraft

associateRole​

Role the Associate holds within a Business Unit.

inheritance​

Determines whether the AssociateRoleAssignment can be inherited by child Business Units.

Can be Disabled, or Enabled​

AssociateInheritanceMode

Disabled
Enabled

BusinessUnitAssociateMode

Explicit
ExplicitAndFromParent

BusinessUnitApprovalRuleMode

Explicit
ExplicitAndFromParent

AsAssociateArgument

businessUnitKey​
associateId​
String​

BusinessUnitUpdateAction

addAddress​
addAssociate​
addBillingAddressId​
addShippingAddressId​
addStore​
changeAddress​
changeAssociate​
changeAssociateMode​
changeName​
changeParentUnit​
changeStatus​
removeAddress​
removeAssociate​
removeBillingAddressId​
removeShippingAddressId​
removeStore​
setAddressCustomField​
setAddressCustomType​
setAssociates​
setContactEmail​
setCustomField​
setCustomType​
setDefaultBillingAddress​
setDefaultShippingAddress​
setStores​
setStoreMode​
changeApprovalRuleMode​
setUnitType​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
addCustomerGroupAssignment​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
removeCustomerGroupAssignment​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
setCustomerGroupAssignments​
BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta

Update actions

Addresses

Add Address

Adding an address to a Business Unit generates a BusinessUnitAddressAdded Message.
address​
Address to add to the addresses of the Business Unit.

Change Address

Changing the address on a Business Unit generates the BusinessUnitAddressChanged Message.
addressId​
String​
ID of the address to change. Either addressId or addressKey is required.
addressKey​
String​
Key of the address to change. Either addressId or addressKey is required.
address​

New address to set.

Remove Address

Removing the address from a Business Unit generates the BusinessUnitAddressRemoved Message.
addressId​
String​
ID of the address to be removed. Either addressId or addressKey is required.
addressKey​
String​
Key of the address to be removed. Either addressId or addressKey is required.

Add Billing Address ID

Adding a billing address to a Business Unit generates a BusinessUnitBillingAddressAdded Message.
addressId​
String​
ID of the address to add as a billing address. Either addressId or addressKey is required.
addressKey​
String​
Key of the address to add as a billing address. Either addressId or addressKey is required.

Remove Billing Address ID

Removing a billing address from a Business Unit generates a BusinessUnitBillingAddressRemoved Message.
addressId​
String​
ID of the address to be removed from billingAddressIds. Either addressId or addressKey is required.
addressKey​
String​
Key of the address to be removed from billingAddressIds. Either addressId or addressKey is required.

Add Shipping Address ID

Adding a shipping address to a Business Unit generates a BusinessUnitShippingAddressAdded Message.
addressId​
String​
ID of the address to add as a shipping address. Either addressId or addressKey is required.
addressKey​
String​
Key of the address to add as a shipping address. Either addressId or addressKey is required.

Remove Shipping Address ID

Removing a shipping address from a Business Unit generates a BusinessUnitShippingAddressRemoved Message.
addressId​
String​
ID of the address to be removed from shippingAddressIds. Either addressId or addressKey is required.
addressKey​
String​
Key of the address to be removed from shippingAddressIds. Either addressId or addressKey is required.

Set Default Billing Address

Setting the default billing address on a Business Unit generates the BusinessUnitDefaultBillingAddressSet Message.
addressId​
String​
ID of the address to add as a billing address. Either addressId or addressKey is required.
addressKey​
String​
Key of the address to add as a billing address. Either addressId or addressKey is required.

Set Default Shipping Address

Setting the default shipping address on a Business Unit generates a BusinessUnitDefaultShippingAddressSet Message.
addressId​
String​
ID of the address to add as a shipping address. Either addressId or addressKey is required.
addressKey​
String​
Key of the address to add as a shipping address. Either addressId or addressKey is required.

Associates

Add Associate

Adding an Associate to a Business Unit generates a BusinessUnitAssociateAdded Message.
associate​

The Associate to add.

AssociateDraft

The Customer to be part of the Business Unit.
associateRoleAssignments​

Roles assigned to the Associate within a Business Unit.

AssociateRoleAssignmentDraft

associateRole​

Role the Associate holds within a Business Unit.

inheritance​

Determines whether the AssociateRoleAssignment can be inherited by child Business Units.

Can be Disabled, or Enabled​

AssociateInheritanceMode

Disabled
Enabled

Change Associate

Updating the Associate on a Business Unit generates the BusinessUnitAssociateChanged Message.
associate​

New version of an existing Associate.

AssociateDraft

The Customer to be part of the Business Unit.
associateRoleAssignments​

Roles assigned to the Associate within a Business Unit.

AssociateRoleAssignmentDraft

associateRole​

Role the Associate holds within a Business Unit.

inheritance​

Determines whether the AssociateRoleAssignment can be inherited by child Business Units.

Can be Disabled, or Enabled​

AssociateInheritanceMode

Disabled
Enabled

Remove Associate

Removing an Associate from a Business Unit generates a BusinessUnitAssociateRemoved Message.
Associate to remove.

Set Associates

Changes the Associates of a Business Unit, generates a BusinessUnitAssociatesSet Message.
associates​
Array of AssociateDraft​

The new list of Associates. Set to an empty array to remove all existing values.

Default: []​

AssociateDraft

The Customer to be part of the Business Unit.
associateRoleAssignments​

Roles assigned to the Associate within a Business Unit.

AssociateRoleAssignmentDraft

associateRole​

Role the Associate holds within a Business Unit.

inheritance​

Determines whether the AssociateRoleAssignment can be inherited by child Business Units.

Can be Disabled, or Enabled​

AssociateInheritanceMode

Disabled
Enabled

Change Associate Mode

Only Business Units of type Division can be changed to ExplicitAndFromParent. This update action generates a BusinessUnitAssociateModeChanged Message.
associateMode​
The new value for associateMode.
Can be Explicit, or ExplicitAndFromParent​
makeInheritedAssociatesExplicit​
Boolean​
Whether all inherited Associates are converted to explicit Associates during a change to associateMode="Explicit".
Default: false​

BusinessUnitAssociateMode

Explicit
ExplicitAndFromParent

Stores

Add Store

Adding a Store to a Business Unit generates a BusinessUnitStoreAdded Message. Only applicable when storeMode is Explicit.
Store to add.

Remove Store

Removes a Store from the Business Unit. Newly created Carts and Orders can no longer reference the removed Store for the Business Unit. We recommend cleaning up unordered Carts that still have the Store assigned after calling this update action since those cannot be converted to Orders. Orders created before the Store was removed remain unchanged. Generates a BusinessUnitStoreRemoved Message. Only applicable when storeMode is Explicit.
Store to remove.

Set Stores

Sets the Stores of the Business Unit. Can only be set if the Business Unit storeMode is Explicit. Carts and Orders created after the Set Stores update must use the new Stores of the Business Unit and, if set, their Product Selections, and Channels. Orders created before the Set Stores update action remain unchanged. Setting the Stores on a Business Unit generates a BusinessUnitStoresSet Message.
stores​
Stores to set. Overrides the current list of Stores.

Set Store Mode

Only Business Units of type Division can be have a store mode of FromParent. Changing the storeMode to FromParent empties the stores array on the BusinessUnit. This update action generates a BusinessUnitStoreModeChanged Message.
stores​
Set the Stores the Business Unit is associated with. Can only be set if storeMode is Explicit.
storeMode​
String​
Set to Explicit to specify Stores for the Business Unit. Set to FromParent to inherit Stores from a parent.

Customer Group Assignments

Add Customer Group Assignment

customerGroupAssignment​

Remove Customer Group Assignment

customerGroup​

Set Customer Group Assignments

customerGroupAssignments​

Custom Fields

Set Custom Type

fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set Custom Field

Adding a Custom Field to a Business Unit generates the BusinessUnitCustomFieldAdded Message, removing one generates the BusinessUnitCustomFieldRemoved Message, and updating an existing one generates the BusinessUnitCustomFieldChanged Message.
name​
String​
Name of the Custom Field to add, update, or remove.
value​
String​
If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, it is set for the field defined by name.

Set Address Custom Type

addressId​
String​
addressKey​
String​
fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set Address Custom Field

addressId​
String​
addressKey​
String​
name​
String​
value​
String​

Hierarchy and settings

Change Name

Updating the name on a Business Unit generates a BusinessUnitNameChanged Message.
name​
String​

New name to set.

Change Parent Unit

This action generates a BusinessUnitParentChanged Message.
parentUnit​
New parent unit of the Business Unit. It must be associated with the same Stores, as the old parent unit.
The Business Unit inheritedAssociates and inheritedStores field values will be eventually consistent.

Change Status

Changing the status of a Business Unit generates a BusinessUnitStatusChanged Message.
status​

New status to set.

Can be Active, or Inactive​

BusinessUnitStatus

Active
Inactive

Change Approval Rule Mode

Updates Approval Rules inheritance behavior between Business Units.
Only Business Units of type Division can be changed to ExplicitAndFromParent.
This update action generates a BusinessUnitApprovalRuleModeChanged Message.
approvalRuleMode​
The new value for approvalRuleMode.
Can be Explicit, or ExplicitAndFromParent​

BusinessUnitApprovalRuleMode

Explicit
ExplicitAndFromParent

Set Contact Email

Setting the contact email on a Business Unit generates a BusinessUnitContactEmailSet Message.
contactEmail​
String​
Email to set. If contactEmail is absent or null, the existing contact email, if any, will be removed.

Set Unit Type

BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta
unitType​
New type of the Business Unit.
If unitType="Company", the Business Unit storeMode, associateMode, and approvalRuleMode field values must be Explicit.
Can be Company, or Division​
parentUnit​
New parent unit for the Business Unit, if unitType="Division".

BusinessUnitType

Company
Division