Associate Business Units
This feature is part of Composable Commerce for B2B and will be subject to additional terms and pricing.
Associate Business Units allow Associates to interact with Business Units.
Associates can view, create, and update Business Units. The actions a given Associate is allowed to perform depends on the specific roles and permissions they hold within a Business Unit.
Get BusinessUnit as Associate
Get BusinessUnit by ID
view_business_units:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
associateId String |
|
id String |
|
expand | The parameter can be passed multiple times. |
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units/{id} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"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" : [ ]}
Get BusinessUnit by Key
view_business_units:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
associateId String |
|
key String |
|
expand | The parameter can be passed multiple times. |
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units/key={key} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"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" : [ ]}
Query BusinessUnits as Associate
Query BusinessUnits by Associate ID
view_business_units:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
associateId String |
|
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. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to |
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"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" : [ ],"storeMode" : "Explicit","stores" : [ ]} ]}
Create BusinessUnit as Associate
When creating a Division, the Associate must have the AddChildUnits
Permission in the parent unit. If the required Permission is missing, an AssociateMissingPermission error is returned.
manage_business_units:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
associateId String |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units -i \--header 'Authorization: Bearer ${BEARER_TOKEN}' \--header 'Content-Type: application/json' \--data-binary @- << DATA{"name" : "commercetools","unitType" : "Company","key" : "commercetools"}DATA
{"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" : [ ]}
Update BusinessUnit as Associate
The Associate must have sufficient Permissions to perform update actions:
UpdateAssociates
for addAssociate, setAssociates, changeAssociate, and removeAssociate update actions.UpdateParentUnit
for the changeParentUnit update action.UpdateBusinessUnitDetails
for all other update actions.
If a required Permission is missing, an AssociateMissingPermission error is returned.
Update BusinessUnit by ID
manage_business_units:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
associateId String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the BusinessUnit on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict error will be returned. |
actions Array of BusinessUnitUpdateAction | Update actions to be performed on the BusinessUnit. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/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
{"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" : [ ]}
Update BusinessUnit by Key
manage_business_units:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
associateId String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the BusinessUnit on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict error will be returned. |
actions Array of BusinessUnitUpdateAction | Update actions to be performed on the BusinessUnit. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/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
{"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" : [ ]}