Business Units

Elevate, May 20-22-2025, Miami Beach, Florida

This feature is part of Composable Commerce for B2B and will be subject to additional terms and pricing.

Business Units are representations of Companies or Divisions. They allow you to model the structure of a business and the access rights of its users.

Business Units can have a set of Associates assigned to them. Associates are represented as Customers that hold different Associate Roles. The Associate Roles are used to grant Associates different permissions.

Business Units can be organized hierarchically up to a maximum of 5 levels, with the top level being a Business Unit of type Company. Divisions can support inheritance, which allows them to inherit Stores, Associates and their roles, and Approval Rules from parent units higher up in the hierarchy.

Carts, Orders, Quotes, and Quote Requests can reference Business Units. Business Units can be used to model company-specific products, pricing, and discounts with the help of Stores, Product Selections, and Channels.

Representations

BusinessUnit

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

id​
String​

Unique identifier of the Business Unit.

(identifier)​
version​
Int​

Current version of the Business Unit.

key​
String​

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

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
status​

Indicates whether the Business Unit can be edited and used in Orders.

stores​
Array of StoreKeyReference​

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, Quotes, or Quote Requests must belong to one of the Business Unit's Stores.

If the Business Unit has no Stores, then all of its Carts, Orders, Quotes, or Quote Requests must not belong to any Store.

inheritedStores​
Array of StoreKeyReference​

Stores that are inherited from a parent Business Unit. The value of this field is eventually consistent and is only present when the storeMode is set to FromParent.

storeMode​

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.

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.

shippingAddressIds​
Array of String​

Unique identifiers of addresses used as shipping addresses.

defaultShippingAddressId​
String​

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

billingAddressIds​
Array of String​

Unique identifiers of addresses used as billing addresses.

defaultBillingAddressId​
String​

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

associateMode​

Set to Explicit to prevent the Business Unit inheriting Associates from a parent, set to ExplicitAndFromParent to enable inheritance.

associates​
Array of Associate​

Associates that are part of the Business Unit in specific roles.

MaxItems: 2000​
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.

parentUnit​

Parent unit of the Business Unit. Only present when the unitType is Division.

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.

custom​
CustomFields​

Custom Fields for the Business Unit.

createdAt​
DateTime​

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

createdBy​
CreatedBy​

IDs and references that created the BusinessUnit.

(beta)​
lastModifiedAt​
DateTime​

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

lastModifiedBy​

IDs and references that last modified the BusinessUnit.

(beta)​

Company

Business Unit type to represent the top level of a business. Contains specific fields and values that differentiate a Company from the generic BusinessUnit.

storeMode​

The value of this field is always Explicit because a Company cannot have a parent Business Unit that Stores can be inherited from.

unitType​
Company

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

associateMode​

The value of this field is always Explicit because a Company cannot have a parent Business Unit that Associates can be inherited from.

approvalRuleMode​

The value of this field is always Explicit because a Company cannot have a parent Business Unit that Approval Rules can be inherited from.

Default: Explicit​

Division

Business Unit type to model divisions that are part of the Company or a higher-order Division. Contains specific fields and values that differentiate a Division from the generic BusinessUnit.

storeMode​

Defines whether the Stores of the Division are set explicitly or inherited from a parent Business Unit.

Default: FromParent​
unitType​
Division

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

associateMode​

Determines whether the Division can inherit Associates from a parent.

Default: ExplicitAndFromParent​
parentUnit​

Parent unit of the Division.

approvalRuleMode​

Determines whether a Business Unit can inherit Approval Rules from a parent.

Default: ExplicitAndFromParent​

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.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
status​

Indicates whether the Business Unit can be edited and used in Orders.

Default: Active​
stores​
Array of StoreResourceIdentifier​

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, Quotes, or Quote Requests must belong to one of the Business Unit's Stores.

If the Business Unit has no Stores, then all of its Carts, Orders, Quotes, or Quote Requests must not belong to any Store.

storeMode​

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.

unitType​

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

name​
String​

Name of the Business Unit.

contactEmail​
String​

Email address of the Business Unit.

associateMode​

Determines whether the Business Unit can inherit Associates from a parent. Always Explicit for Companies and defaults to ExplicitAndFromParent for Divisions.

associates​
Array of AssociateDraft​

List of members that are part of the Business Unit in specific roles.

MaxItems: 2000​
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.

addresses​
Array of BaseAddress​

Addresses used by the Business Unit.

shippingAddresses​
Array of Integer​

Indexes of entries in addresses to set as shipping addresses. The shippingAddressIds of the Customer will be replaced by these addresses.

defaultShippingAddress​
Int​

Index of the entry in addresses to set as the default shipping address.

billingAddresses​
Array of Integer​

Indexes of entries in addresses to set as billing addresses. The billingAddressIds of the Customer will be replaced by these addresses.

defaultBillingAddress​
Int​

Index of the entry in addresses to set as the default billing address.

custom​

Custom Fields for the Business Unit.

CompanyDraft

Draft type to represent the top level of a business. Contains the fields and values of the generic BusinessUnitDraft that are used specifically for creating a Company.

unitType​
Company

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

DivisionDraft

Draft type to model divisions that are part of a Company or a higher-order Division. Contains the fields and values of the generic BusinessUnitDraft that are used specifically for creating a Division.

storeMode​

If not set, the Division inherits the Stores from a parent unit. Set this to Explicit if you want to set the Stores explicitly in the stores field instead.

Default: FromParent​
unitType​
Division

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

associateMode​

Determines whether the Division can inherit Associates from a parent.

Default: ExplicitAndFromParent​
approvalRuleMode​

Determines whether the Division can inherit Approval Rules from a parent.

Default: ExplicitAndFromParent​
parentUnit​

The parent unit of this Division. Can be a Company or a Division.

Associate

associateRoleAssignments​
Array of AssociateRoleAssignment​

Roles assigned to the Associate within a Business Unit.

MaxItems: 5​
roles​
Array of AssociateRoleDeprecated​

Deprecated type. Use associateRoleAssignments instead.

(deprecated)​
customer​

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

AssociateDraft

associateRoleAssignments​

Roles assigned to the Associate within a Business Unit.

MinItems: 1​MaxItems: 5​
roles​
Array of AssociateRoleDeprecated​

Deprecated type. Use associateRoleAssignments instead.

(deprecated)​
customer​

The Customer to be part of the Business Unit.

AssociateRoleAssignment

associateRole​

Role the Associate holds within a Business Unit.

inheritance​

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

Default: Disabled​

AssociateRoleAssignmentDraft

associateRole​

Role the Associate holds within a Business Unit.

inheritance​

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

Default: Disabled​

AssociateRoleInheritanceMode

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

Enabled

The assignment can be inherited by child Business Units.

Disabled

The assignment cannot be inherited by child Business Units.

InheritedAssociate

associateRoleAssignments​

Inherited roles of the Associate within a Business Unit.

customer​

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

InheritedAssociateRoleAssignment

associateRole​

Inherited role the Associate holds within a Business Unit.

source​

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

BusinessUnitStatus

Indicates whether the Business Unit can be edited and used in Carts, Orders, Quote Requests, or Quotes.

Active

The Business Unit can be used in Carts, Orders, Quote Requests, and Quotes and can be edited.

Inactive

The Business Unit cannot be used in Carts, Orders, Quote Requests, and Quotes and can only be edited using the general endpoint. Status doesn't affect inheritance. Even if a parent unit is inactive, its children remain active and can inherit role assignments.

BusinessUnitType

The type of the Business Unit indicating its position in a hierarchy.

Company

Top-level Business Unit. Must not have a parentUnit defined.

Division

Business Unit with a parentUnit reference to a Company or another Division.

BusinessUnitAssociateMode

Determines whether a Business Unit can inherit Associates from a parent.

Explicit

All Associates of a Business Unit must be explicitly assigned. The Business Unit cannot inherit Associates from a parent.

ExplicitAndFromParent

Associates of a Business Unit can be assigned explicitly and inherited from a parent.

BusinessUnitApprovalRuleMode

Determines whether a Business Unit can inherit Approval Rules from a parent. Only Business Units of type Division can use ExplicitAndFromParent.

Explicit

Approval Rules of a Business Unit must be explicitly assigned. The Business Unit cannot inherit Approval Rules from a parent.

ExplicitAndFromParent

Approval Rules of a Business Unit are inherited from a parent and can also be explicitly assigned.

BusinessUnitStoreMode

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

Explicit

Stores are defined on the Business Unit.

FromParent

Stores are inherited from the closest parent in the hierarchy that has Stores defined.

BusinessUnitPagedQueryResponse

PagedQueryResult with results containing an array of BusinessUnit.

limit​
Int​

Number of requested results.

offset​
Int​

Number of elements skipped.

count​
Int​

Actual number of results returned.

total​
Int​

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

results​
Array of BusinessUnit​

BusinessUnits matching the query.

BusinessUnitReference

id​
String​

Unique identifier of the referenced BusinessUnit.

typeId​
business-unit

Type of referenced resource.

obj​
BusinessUnit​

Contains the representation of the expanded BusinessUnit. Only present in responses to requests with Reference Expansion for BusinessUnit.

BusinessUnitKeyReference

key​
String​

Unique and immutable key of the referenced BusinessUnit.

typeId​
business-unit

Type of referenced resource.

BusinessUnitResourceIdentifier

ResourceIdentifier to a BusinessUnit. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

id​
String​

Unique identifier of the referenced BusinessUnit. Required if key is absent.

key​
String​

Unique key of the referenced BusinessUnit. Required if id is absent.

typeId​
business-unit

Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

Get BusinessUnit

Get BusinessUnit by ID

GET
https://api.{region}.commercetools.com/{projectKey}/business-units/{id}
OAuth 2.0 Scopes:
view_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the BusinessUnit.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/business-units/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Get BusinessUnit by Key

GET
https://api.{region}.commercetools.com/{projectKey}/business-units/key={key}
OAuth 2.0 Scopes:
view_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the BusinessUnit.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/business-units/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Get BusinessUnit in Store

Get BusinessUnit in Store by ID

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/{id}
OAuth 2.0 Scopes:
view_business_units:{projectKey}view_business_units:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

id
​
String
​

id of the BusinessUnit.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Get BusinessUnit in Store by Key

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/key={key}
OAuth 2.0 Scopes:
view_business_units:{projectKey}view_business_units:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

key
​
String
​

key of the BusinessUnit.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Query BusinessUnits

GET
https://api.{region}.commercetools.com/{projectKey}/business-units
OAuth 2.0 Scopes:
view_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​​
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
​

Any string parameter matching this regular expression

​

Predicate parameter values.

The parameter can be passed multiple times.
sort
​​
The parameter can be passed multiple times.
expand
​​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

Default: 20​
offset
​
Int
​

Number of elements skipped.

0
withTotal
​
Boolean
​

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Default: ​
Response:
200

BusinessUnitPagedQueryResponse

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/business-units -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: BusinessUnitPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
      "version": 5,
      "createdAt": "2022-04-19T15:36:17.510Z",
      "lastModifiedAt": "2022-04-20T15:41:55.816Z",
      "name": "commercetools",
      "unitType": "Company",
      "key": "commercetools",
      "status": "Active",
      "topLevelUnit": {
        "typeId": "business-unit",
        "key": "commercetools"
      },
      "addresses": [],
      "associates": [],
      "associateMode": "Explicit",
      "inheritedAssociates": [],
      "approvalRuleMode": "Explicit",
      "storeMode": "Explicit",
      "stores": []
    }
  ]
}

Query BusinessUnits in Store

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units
OAuth 2.0 Scopes:
view_business_units:{projectKey}view_business_units:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

Query parameters:
where
​​
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
​

Any string parameter matching this regular expression

​

Predicate parameter values.

The parameter can be passed multiple times.
sort
​​
The parameter can be passed multiple times.
expand
​​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

Default: 20​
offset
​
Int
​

Number of elements skipped.

0
withTotal
​
Boolean
​

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Default: ​
Response:
200

BusinessUnitPagedQueryResponse

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: BusinessUnitPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
      "version": 5,
      "createdAt": "2022-04-19T15:36:17.510Z",
      "lastModifiedAt": "2022-04-20T15:41:55.816Z",
      "name": "commercetools",
      "unitType": "Company",
      "key": "commercetools",
      "status": "Active",
      "topLevelUnit": {
        "typeId": "business-unit",
        "key": "commercetools"
      },
      "addresses": [],
      "associates": [],
      "associateMode": "Explicit",
      "inheritedAssociates": [],
      "approvalRuleMode": "Explicit",
      "storeMode": "Explicit",
      "stores": []
    }
  ]
}

Check if BusinessUnit exists

Check if BusinessUnit exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/business-units/{id}

Checks if a BusinessUnit exists for a given id. Returns a 200 OK status if the BusinessUnit exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the BusinessUnit.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/business-units/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if BusinessUnit exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/business-units/key={key}

Checks if a BusinessUnit exists for a given key. Returns a 200 OK status if the BusinessUnit exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the BusinessUnit.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/business-units/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if BusinessUnit exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/business-units

Checks if a BusinessUnit exists for a given Query Predicate. Returns a 200 OK status if any BusinessUnits match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​​
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/business-units -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if BusinessUnit exists in Store

Check if BusinessUnit exists in Store by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/{id}

Checks if a BusinessUnit exists for a given id. Returns a 200 OK status if the BusinessUnit exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_business_units:{projectKey}view_business_units:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

id
​
String
​

id of the BusinessUnit.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if BusinessUnit exists in Store by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/key={key}

Checks if a BusinessUnit exists for a given key. Returns a 200 OK status if the BusinessUnit exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_business_units:{projectKey}view_business_units:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

key
​
String
​

key of the BusinessUnit.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if BusinessUnit exists in Store by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units

Checks if a BusinessUnit exists for a given Query Predicate. Returns a 200 OK status if any BusinessUnits match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_business_units:{projectKey}view_business_units:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

Query parameters:
where
​​
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Create BusinessUnit

Creating a Business Unit produces the BusinessUnitCreated Message.

POST
https://api.{region}.commercetools.com/{projectKey}/business-units
OAuth 2.0 Scopes:
manage_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:BusinessUnitDraftasapplication/json
Response:
201

BusinessUnit

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/business-units -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "name" : "commercetools",
  "unitType" : "Company",
  "key" : "commercetools"
}
DATA
201 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Create BusinessUnit in Store

Creating a Business Unit produces the BusinessUnitCreated Message.

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units
OAuth 2.0 Scopes:
manage_business_units:{projectKey}manage_business_units:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:BusinessUnitDraftasapplication/json
Response:
201

BusinessUnit

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "name" : "commercetools",
  "unitType" : "Company",
  "key" : "commercetools"
}
DATA
201 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Update BusinessUnit

Update BusinessUnit by ID

POST
https://api.{region}.commercetools.com/{projectKey}/business-units/{id}
OAuth 2.0 Scopes:
manage_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the BusinessUnit.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:BusinessUnitUpdateasapplication/json
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/business-units/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 3,
  "actions" : [ {
    "action" : "addAddress",
    "address" : {
      "streetName" : "Any Street",
      "streetNumber" : "1337",
      "postalCode" : "11111",
      "city" : "Any City",
      "country" : "US"
    }
  } ]
}
DATA
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Update BusinessUnit by Key

POST
https://api.{region}.commercetools.com/{projectKey}/business-units/key={key}
OAuth 2.0 Scopes:
manage_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the BusinessUnit.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:BusinessUnitUpdateasapplication/json
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/business-units/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 3,
  "actions" : [ {
    "action" : "addAddress",
    "address" : {
      "streetName" : "Any Street",
      "streetNumber" : "1337",
      "postalCode" : "11111",
      "city" : "Any City",
      "country" : "US"
    }
  } ]
}
DATA
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Update BusinessUnit in Store

Update BusinessUnit in Store by ID

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/{id}
OAuth 2.0 Scopes:
manage_business_units:{projectKey}manage_business_units:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

id
​
String
​

id of the BusinessUnit.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:BusinessUnitUpdateasapplication/json
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 3,
  "actions" : [ {
    "action" : "addAddress",
    "address" : {
      "streetName" : "Any Street",
      "streetNumber" : "1337",
      "postalCode" : "11111",
      "city" : "Any City",
      "country" : "US"
    }
  } ]
}
DATA
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Update BusinessUnit in Store by Key

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/key={key}
OAuth 2.0 Scopes:
manage_business_units:{projectKey}manage_business_units:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

key
​
String
​

key of the BusinessUnit.

Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:BusinessUnitUpdateasapplication/json
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 3,
  "actions" : [ {
    "action" : "addAddress",
    "address" : {
      "streetName" : "Any Street",
      "streetNumber" : "1337",
      "postalCode" : "11111",
      "city" : "Any City",
      "country" : "US"
    }
  } ]
}
DATA
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Update actions

Add Address

Adding an address to a Business Unit generates a BusinessUnitAddressAdded Message.

action​
String​
"addAddress"
address​
BaseAddress​

Address to add to the addresses of the Business Unit.

Example: json
{
  "action": "addAddress",
  "address": {
    "id": "exampleAddress",
    "key": "exampleKey",
    "title": "My Address",
    "salutation": "Mr.",
    "firstName": "Example",
    "lastName": "Person",
    "streetName": "Example Street",
    "streetNumber": "4711",
    "additionalStreetInfo": "Backhouse",
    "postalCode": "80933",
    "city": "Exemplary City",
    "region": "Exemplary Region",
    "state": "Exemplary State",
    "country": "DE",
    "company": "My Company Name",
    "department": "Sales",
    "building": "Hightower 1",
    "apartment": "247",
    "pOBox": "2471",
    "phone": "+49 89 12345678",
    "mobile": "+49 171 2345678",
    "email": "mail@example.com",
    "fax": "+49 89 12345679",
    "additionalAddressInfo": "no additional Info",
    "externalId": "Information not needed"
  }
}

Add Associate

To add Associates in bulk to Business Units, use the Set Associates action instead.

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

action​
String​
"addAssociate"
associate​

The Associate to add.

Example: json
{
  "action": "addAssociate",
  "associate": {
    "customer": {
      "typeId": "customer",
      "id": "some-customer-id"
    },
    "associateRoleAssignments": [
      {
        "associateRole": {
          "typeId": "associate-role",
          "key": "admin"
        },
        "inheritance": "Enabled"
      },
      {
        "associateRole": {
          "typeId": "associate-role",
          "key": "buyer"
        }
      }
    ]
  }
}

Add Billing Address Identifier

Adding a billing address to a Business Unit generates a BusinessUnitBillingAddressAdded Message.

action​
String​
"addBillingAddressId"
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.

Example: json
{
  "action": "addBillingAddressId",
  "addressId": "{{addressId}}"
}

Add Shipping Address Identifier

Adding a shipping address to a Business Unit generates a BusinessUnitShippingAddressAdded Message.

action​
String​
"addShippingAddressId"
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.

Example: json
{
  "action": "addShippingAddressId",
  "addressId": "{{addressId}}"
}

Add Store

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

action​
String​
"addStore"
store​

Store to add.

Example: json
{
  "action": "addStore",
  "store": {
    "key": "{{store-key}}",
    "typeId": "store"
  }
}

Change Address

Changing the address on a Business Unit generates the BusinessUnitAddressChanged Message.

action​
String​
"changeAddress"
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​
BaseAddress​

New address to set.

Example: json
{
  "action": "changeAddress",
  "addressId": "{{addressId}}",
  "address": {
    "id": "exampleAddress",
    "key": "exampleKey",
    "title": "My Address",
    "salutation": "Mr.",
    "firstName": "Example",
    "lastName": "Person",
    "streetName": "Example Street",
    "streetNumber": "4711",
    "additionalStreetInfo": "Backhouse",
    "postalCode": "80933",
    "city": "Exemplary City",
    "region": "Exemplary Region",
    "state": "Exemplary State",
    "country": "DE",
    "company": "My Company Name",
    "department": "Sales",
    "building": "Hightower 1",
    "apartment": "247",
    "pOBox": "2471",
    "phone": "+49 89 12345678",
    "mobile": "+49 171 2345678",
    "email": "email@example.com",
    "fax": "+49 89 12345679",
    "additionalAddressInfo": "no additional Info",
    "externalId": "Information not needed"
  }
}

Change Associate

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

action​
String​
"changeAssociate"
associate​

New version of an existing Associate.

Example: json
{
  "action": "changeAssociate",
  "associate": {
    "customer": {
      "typeId": "customer",
      "id": "some-customer-id"
    },
    "associateRoleAssignments": [
      {
        "associateRole": {
          "typeId": "associate-role",
          "key": "admin"
        },
        "inheritance": "Enabled"
      },
      {
        "associateRole": {
          "typeId": "associate-role",
          "key": "buyer"
        }
      }
    ]
  }
}

Change Associate Mode

Only Business Units of type Division can be changed to ExplicitAndFromParent. This update action generates a BusinessUnitAssociateModeChanged Message.

action​
String​
"changeAssociateMode"
associateMode​

The new value for associateMode.

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.

action​
String​
"changeApprovalRuleMode"
approvalRuleMode​

The new value for approvalRuleMode.

Example: json
{
  "action": "changeApprovalRuleMode",
  "approvalRuleMode": "Explicit"
}

Change Name

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

action​
String​
"changeName"
name​
String​

New name to set.

Example: json
{
  "action": "changeName",
  "name": "commercetools"
}

Change Parent Unit

Changing the parent of a Business Unit generates a BusinessUnitParentChanged Message.

action​
String​
"changeParentUnit"
parentUnit​

New parent unit of the Business Unit. The new parent unit must have the same top-level unit as the old parent unit.

Example: json
{
  "action": "changeParentUnit",
  "parentUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  }
}

Change Status

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

action​
String​
"changeStatus"
status​
String​

New status to set.

Example: json
{
  "action": "changeStatus",
  "status": "Inactive"
}

Remove Address

Removing the address from a Business Unit generates the BusinessUnitAddressRemoved Message.

action​
String​
"removeAddress"
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.

Example: json
{
  "action": "removeAddress",
  "addressId": "{{addressId}}"
}

Remove Associate

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

action​
String​
"removeAssociate"
customer​

Associate to remove.

Example: json
{
  "action": "removeAssociate",
  "customer": {
    "typeId": "customer",
    "id": "some-customer-id"
  }
}

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.

action​
String​
"removeStore"
store​

Store to remove.

Example: json
{
  "action": "removeStore",
  "store": {
    "key": "{{store-key}}",
    "typeId": "store"
  }
}

Remove Billing Address Identifier

Removing a billing address from a Business Unit generates a BusinessUnitBillingAddressRemoved Message.

action​
String​
"removeBillingAddressId"
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.

Example: json
{
  "action": "removeBillingAddressId",
  "addressId": "{{addressId}}"
}

Remove Shipping Address Identifier

Removing a shipping address from a Business Unit generates a BusinessUnitShippingAddressRemoved Message.

action​
String​
"removeShippingAddressId"
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.

Example: json
{
  "action": "removeShippingAddressId",
  "addressId": "{{addressId}}"
}

Set Address CustomField

Adding a Custom Field to an Address of a Business Unit generates the BusinessUnitAddressCustomFieldAdded Message, removing one generates the BusinessUnitAddressCustomFieldRemoved Message, and updating an existing one generates the BusinessUnitAddressCustomFieldChanged Message.

action​
String​
"setAddressCustomField"
addressId​
String​

ID of the address to be extended.

name​
String​

Name of the Custom Field.

value​

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.

Example: json
{
  "action": "setAddressCustomField",
  "name": "exampleStringField",
  "value": "TextString",
  "addressId": "{{address-id}}"
}

Set Associates

Changes the Associates of a Business Unit, generates a BusinessUnitAssociatesSet Message.

action​
String​
"setAssociates"
associates​
Array of AssociateDraft​

The new list of Associates. If empty, existing values will be removed.

MaxItems: 2000​
Example: json
{
  "action": "setAssociates",
  "associates": [
    {
      "customer": {
        "typeId": "customer",
        "id": "some-customer-id"
      },
      "associateRoleAssignments": [
        {
          "associateRole": {
            "typeId": "associate-role",
            "key": "admin"
          },
          "inheritance": "Enabled"
        }
      ]
    },
    {
      "customer": {
        "typeId": "customer",
        "id": "another-customer-id"
      },
      "associateRoleAssignments": [
        {
          "associateRole": {
            "typeId": "associate-role",
            "key": "buyer"
          }
        }
      ]
    }
  ]
}

Set Custom Type in Address

Adding or updating a Custom Type on an Address of a Business Unit generates the BusinessUnitAddressCustomTypeSet Message, and removing one generates the BusinessUnitAddressCustomTypeRemoved Message.

action​
String​
"setAddressCustomType"
type​

Defines the Type that extends the address with Custom Fields. If absent, any existing Type and Custom Fields are removed from the address.

fields​

Sets the Custom Fields for the address.

addressId​
String​

ID of the address to be extended.

Example: json
{
  "action": "setAddressCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  },
  "addressId": "{{address-id}}"
}

Set Contact Email

Setting the contact email on a Business Unit generates a BusinessUnitContactEmailSet Message.

action​
String​
"setContactEmail"
contactEmail​
String​

Email to set. If contactEmail is absent or null, the existing contact email, if any, will be removed.

Example: json
{
  "action": "setContactEmail",
  "contactEmail": "contact@example.com"
}

Set CustomField

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.

action​
String​
"setCustomField"
name​
String​

Name of the Custom Field to add, update, or remove.

value​

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.

Example: json
{
  "action": "setCustomField",
  "name": "exampleStringField",
  "value": "TextString"
}

Set Custom Type

Adding or updating a Custom Type on a Business Unit generates the BusinessUnitCustomTypeSet Message, removing one generates the BusinessUnitCustomTypeRemoved Message.

action​
String​
"setCustomType"
type​

Defines the Type that extends the BusinessUnit with Custom Fields. If absent, any existing Type and Custom Fields are removed from the BusinessUnit.

fields​

Sets the Custom Fields for the BusinessUnit.

Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set Default Billing Address

Setting the default billing address on a Business Unit generates the BusinessUnitDefaultBillingAddressSet Message.

action​
String​
"setDefaultBillingAddress"
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.

Example: json
{
  "action": "setDefaultBillingAddress",
  "addressId": "{{addressId}}"
}

Set Default Shipping Address

Setting the default shipping address on a Business Unit generates a BusinessUnitDefaultShippingAddressSet Message.

action​
String​
"setDefaultShippingAddress"
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.

Example: json
{
  "action": "setDefaultShippingAddress",
  "addressId": "{{addressId}}"
}

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.

action​
String​
"setStores"
stores​
Array of StoreResourceIdentifier​

Stores to set. Overrides the current list of Stores.

Example: json
{
  "action": "setStores",
  "stores": [
    {
      "key": "{{store-key}}",
      "typeId": "store"
    }
  ]
}

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.

action​
String​
"setStoreMode"
storeMode​

Set to Explicit to specify Stores for the Business Unit. Set to FromParent to inherit Stores from a parent.

stores​
Array of StoreResourceIdentifier​

Set the Stores the Business Unit is associated with. Can only be set if storeMode is Explicit.

Example: json
{
  "action": "setStoreMode",
  "storeMode": "FromParent"
}

Delete BusinessUnit

Deleting a Business Unit produces the BusinessUnitDeleted Message. A Business Unit can only be deleted if it is not referenced by a Cart, Order, Quote, Shopping List, or another Business Unit.

Delete BusinessUnit by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/business-units/{id}
OAuth 2.0 Scopes:
manage_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the BusinessUnit.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​​
The parameter can be passed multiple times.
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/business-units/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Delete BusinessUnit by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/business-units/key={key}
OAuth 2.0 Scopes:
manage_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the BusinessUnit.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​​
The parameter can be passed multiple times.
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/business-units/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Delete BusinessUnit in Store

Deleting a Business Unit produces the BusinessUnitDeleted Message. A Business Unit can only be deleted if it is not referenced by a Cart, Order, Quote, or another Business Unit.

Delete BusinessUnit in Store by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/{id}
OAuth 2.0 Scopes:
manage_business_units:{projectKey}manage_business_units:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

id
​
String
​

id of the BusinessUnit.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​​
The parameter can be passed multiple times.
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Delete BusinessUnit in Store by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/key={key}
OAuth 2.0 Scopes:
manage_business_units:{projectKey}manage_business_units:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

key
​
String
​

key of the BusinessUnit.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​​
The parameter can be passed multiple times.
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/business-units/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

GraphQL query fields

In addition to the fields available on the REST API, the GraphQL API for Business Units supports two additional fields: ancestors and inheritedStores.

Ancestors

The ancestors field returns a list of all the parent Business Units of the queried Business Unit. The list is ordered from the top-level Company to the parent unit of the Business Unit.

query {
  businessUnit(key: "sub-division") {
    ancestors {
      key
      name
      contactEmail
      status
    }
  }
}

Inherited Stores

The inheritedStores field returns a list of the Stores a Business Unit inherits from its parent. For a Company, or a Division with storeMode set to Explicit, this field is null.

query {
  businessUnit(key: "sub-division") {
    inheritedStores {
      store {
        key
        supplyChannels {
          id
          key
          roles
        }
      }
    }
  }
}