Queries and mutations for managing Business Units in the platform.
Queries
Query Business Units
| Arguments | |
|---|---|
whereString | |
sortArray of String | |
limitInt | |
offsetInt | |
Get Business Unit
| Arguments | |
|---|---|
idString | Queries with specified ID |
keyString | Queries with specified key |
Get Associate in Business Unit
| Arguments | |
|---|---|
businessUnitIdString | Queries with specified Business Unit ID |
businessUnitKeyString | Queries with specified Business Unit key |
associateIdString | Queries the specific associate within the Business Unit |
Mutations
updateBusinessUnit takes a list of update actions. For behavior, see Business Units in the HTTP API.Create Business Unit
| 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
| Arguments | |
|---|---|
versionLong | |
actionsArray of BusinessUnitUpdateAction | |
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. |
idString | Queries with specified ID |
keyString | Queries with specified key |
Delete Business Unit
| Arguments | |
|---|---|
versionLong | |
personalDataErasureBoolean | Default: false |
storeKey | The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions. |
idString | Queries with specified ID |
keyString | Queries with specified key |
Output types
BusinessUnit
Generic type to model the fields that all types of Business Units have in common.
idString | Unique identifier of the Business Unit. |
keyString | User-defined unique and immutable identifier of the Business Unit. |
nameString | Name of the Business Unit. |
contactEmailString | Email address of the Business Unit. |
addressesArray of Address | Addresses used by the Business Unit. |
defaultShippingAddress | |
defaultBillingAddress | |
defaultShippingAddressIdString | Unique identifier of the address used as the default shipping address. |
defaultBillingAddressIdString | Unique identifier of the address used as the default billing address. |
shippingAddressesArray of Address | |
billingAddressesArray of Address | |
shippingAddressIdsArray of String | Unique identifiers of addresses used as shipping addresses. |
billingAddressIdsArray 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 |
storesRefArray of KeyReference | 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. |
storesArray of Store | 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. |
storeModeString | 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 beCompany, or Division |
associatesArray of Associate | Associates that are part of the Business Unit in specific roles. |
associateMode | Set to Can be Explicit to prevent the Business Unit inheriting Associates from a parent, set to ExplicitAndFromParent to enable inheritance.Explicit, or ExplicitAndFromParent |
inheritedAssociatesArray 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. |
ancestorsArray of BusinessUnit | This field contains the BusinessUnits KeyReferences from the Company to the parent Division of this BusinessUnit in that order. |
inheritedStoresArray 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 | |
customerGroupAssignmentsArray of CustomerGroupAssignment | BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta |
versionLong | 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
ActiveInactive
BusinessUnitType
CompanyDivision
Associate
associateRoleAssignmentsArray of AssociateRoleAssignment | 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 beDisabled, or Enabled |
AssociateInheritanceMode
DisabledEnabled
BusinessUnitAssociateMode
ExplicitExplicitAndFromParent
InheritedAssociate
associateRoleAssignmentsArray of InheritedAssociateRoleAssignment | 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
ExplicitExplicitAndFromParent
BusinessUnitQueryResult
offsetInt | |
countInt | |
totalLong | |
existsBoolean | |
resultsArray of BusinessUnit |
BusinessUnitAssociateProjection
customerRef | |
customer | |
associateRolesArray of AssociateRole | |
inheritedAssociateRolesArray of AssociateRole | |
permissionsArray 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
AcceptMyQuotesAcceptOthersQuotesAddChildUnitsCreateApprovalRulesCreateMyCartsCreateMyOrdersFromMyCartsCreateMyOrdersFromMyQuotesCreateMyPaymentMethodsCreateMyQuoteRequestsFromMyCartsCreateMyShoppingListsCreateOrdersFromOthersCartsCreateOrdersFromOthersQuotesCreateOthersCartsCreateOthersPaymentMethodsCreateOthersShoppingListsCreateQuoteRequestsFromOthersCartsDeclineMyQuotesDeclineOthersQuotesDeleteMyCartsDeleteMyPaymentMethodsDeleteMyShoppingListsDeleteOthersCartsDeleteOthersPaymentMethodsDeleteOthersShoppingListsReassignMyQuotesReassignOthersQuotesRenegotiateMyQuotesRenegotiateOthersQuotesUpdateApprovalFlowsUpdateApprovalRulesUpdateAssociatesUpdateBusinessUnitDetailsUpdateMyCartsUpdateMyOrdersUpdateMyPaymentMethodsUpdateMyQuoteRequestsUpdateMyShoppingListsUpdateOthersCartsUpdateOthersOrdersUpdateOthersPaymentMethodsUpdateOthersQuoteRequestsUpdateOthersShoppingListsUpdateParentUnitViewMyCartsViewMyOrdersViewMyPaymentMethodsViewMyQuoteRequestsViewMyQuotesViewMyShoppingListsViewOthersCartsViewOthersOrdersViewOthersPaymentMethodsViewOthersQuoteRequestsViewOthersQuotesViewOthersShoppingLists
Input types
BusinessUnitDraft
keyString | User-defined unique and immutable identifier for the Business Unit. |
nameString | Name of the Business Unit. |
contactEmailString | Email address of the Business Unit. |
addressesArray of AddressInput | Addresses used by the Business Unit. |
defaultBillingAddressInt | The index of the address in the addresses list. The defaultBillingAddressId of the customer will be set to the ID of that address. |
defaultShippingAddressInt | The index of the address in the addresses list. The defaultShippingAddressId of the customer will be set to the ID of that address. |
shippingAddressesArray of Int | The indices of the shipping addresses in the Default: addresses list. The shippingAddressIds of the Customer will be set to the IDs of that addresses.[] |
billingAddressesArray of Int | The indices of the billing addresses in the Default: addresses list. The billingAddressIds of the customer will be set to the IDs of that addresses.[] |
custom | Custom Fields for the Business Unit. |
unitType | Type of the Business Unit indicating its position in a hierarchy. Can beCompany, or Division |
storeModeString | |
parentUnit | |
storesArray of ResourceIdentifierInput | 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. |
associatesArray of AssociateDraft | List of members that are part of the Business Unit in specific roles. |
associateMode | |
approvalRuleMode | |
customerGroupAssignmentsArray of CustomerGroupAssignmentDraft | BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta |
BusinessUnitType
CompanyDivision
AssociateDraft
customer | The Customer to be part of the Business Unit. |
associateRoleAssignmentsArray of AssociateRoleAssignmentDraft | 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 beDisabled, or Enabled |
AssociateInheritanceMode
DisabledEnabled
BusinessUnitAssociateMode
ExplicitExplicitAndFromParent
BusinessUnitApprovalRuleMode
ExplicitExplicitAndFromParent
AsAssociateArgument
businessUnitKey | |
associateIdString |
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
address | Address to add to the addresses of the Business Unit. |
Change Address
addressIdString | ID of the address to change. Either addressId or addressKey is required. |
addressKeyString | Key of the address to change. Either addressId or addressKey is required. |
address | New address to set. |
Remove Address
addressIdString | ID of the address to be removed. Either addressId or addressKey is required. |
addressKeyString | Key of the address to be removed. Either addressId or addressKey is required. |
Add Billing Address ID
addressIdString | ID of the address to add as a billing address. Either addressId or addressKey is required. |
addressKeyString | Key of the address to add as a billing address. Either addressId or addressKey is required. |
Remove Billing Address ID
addressIdString | ID of the address to be removed from billingAddressIds. Either addressId or addressKey is required. |
addressKeyString | Key of the address to be removed from billingAddressIds. Either addressId or addressKey is required. |
Add Shipping Address ID
addressIdString | ID of the address to add as a shipping address. Either addressId or addressKey is required. |
addressKeyString | Key of the address to add as a shipping address. Either addressId or addressKey is required. |
Remove Shipping Address ID
addressIdString | ID of the address to be removed from shippingAddressIds. Either addressId or addressKey is required. |
addressKeyString | Key of the address to be removed from shippingAddressIds. Either addressId or addressKey is required. |
Set Default Billing Address
addressIdString | ID of the address to add as a billing address. Either addressId or addressKey is required. |
addressKeyString | Key of the address to add as a billing address. Either addressId or addressKey is required. |
Set Default Shipping Address
addressIdString | ID of the address to add as a shipping address. Either addressId or addressKey is required. |
addressKeyString | Key of the address to add as a shipping address. Either addressId or addressKey is required. |
Associates
Add Associate
associate | The Associate to add. |
AssociateDraft
customer | The Customer to be part of the Business Unit. |
associateRoleAssignmentsArray of AssociateRoleAssignmentDraft | 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 beDisabled, or Enabled |
AssociateInheritanceMode
DisabledEnabled
Change Associate
associate | New version of an existing Associate. |
AssociateDraft
customer | The Customer to be part of the Business Unit. |
associateRoleAssignmentsArray of AssociateRoleAssignmentDraft | 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 beDisabled, or Enabled |
AssociateInheritanceMode
DisabledEnabled
Remove Associate
customer | Associate to remove. |
Set Associates
associatesArray of AssociateDraft | The new list of Associates. Set to an empty array to remove all existing values. Default:[] |
AssociateDraft
customer | The Customer to be part of the Business Unit. |
associateRoleAssignmentsArray of AssociateRoleAssignmentDraft | 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 beDisabled, or Enabled |
AssociateInheritanceMode
DisabledEnabled
Change Associate Mode
Division can be changed to ExplicitAndFromParent.
This update action generates a BusinessUnitAssociateModeChanged Message.associateMode | The new value for Can be associateMode.Explicit, or ExplicitAndFromParent |
makeInheritedAssociatesExplicitBoolean | Whether all inherited Associates are converted to explicit Associates during a change to Default: associateMode="Explicit".false |
BusinessUnitAssociateMode
ExplicitExplicitAndFromParent
Stores
Add Store
storeMode is Explicit.store | Store to add. |
Remove Store
storeMode is Explicit.store | Store to remove. |
Set Stores
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.storesArray of ResourceIdentifierInput | Stores to set. Overrides the current list of Stores. |
Set Store Mode
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.storesArray of ResourceIdentifierInput | |
storeModeString | 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
customerGroupAssignmentsArray of CustomerGroupAssignmentDraft |
Custom Fields
Set Custom Type
fieldsArray of CustomFieldInput | |
type | |
typeKeyString | |
typeIdString |
Set Custom Field
nameString | Name of the Custom Field to add, update, or remove. |
valueString | 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
addressIdString | |
addressKeyString | |
fieldsArray of CustomFieldInput | |
type | |
typeKeyString | |
typeIdString |
Set Address Custom Field
addressIdString | |
addressKeyString | |
nameString | |
valueString |
Hierarchy and settings
Change Name
nameString | New name to set. |
Change Parent Unit
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
status | New status to set. Can beActive, or Inactive |
BusinessUnitStatus
ActiveInactive
Change Approval Rule Mode
Division can be changed to ExplicitAndFromParent.approvalRuleMode | The new value for Can be approvalRuleMode.Explicit, or ExplicitAndFromParent |
BusinessUnitApprovalRuleMode
ExplicitExplicitAndFromParent
Set Contact Email
contactEmailString | Email to set.
If contactEmail is absent or null, the existing contact email, if any, will be removed. |
Set Unit Type
unitType | New type of the Business Unit.
If Can be unitType="Company", the Business Unit storeMode, associateMode, and approvalRuleMode field values must be Explicit.Company, or Division |
parentUnit | New parent unit for the Business Unit, if unitType="Division". |
BusinessUnitType
CompanyDivision