BETA

Associate Business Units

Information icon

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

GET
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/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.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

id
String

id of the BusinessUnit.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
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" : [ ]
}
Clipboard icon

Get BusinessUnit by Key

GET
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/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.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

key
String

key of the BusinessUnit.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
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" : [ ]
}
Clipboard icon

Query BusinessUnits as Associate

Query BusinessUnits by Associate ID

GET
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/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.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

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
offset
Int

Number of elements skipped.

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.

Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
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" : [ ],
"storeMode" : "Explicit",
"stores" : [ ]
} ]
}
Clipboard icon

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.

POST
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/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.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:BusinessUnitDraftasapplication/json
Response:
201BusinessUnitasapplication/json
Request Example:cURL
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
Clipboard icon
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" : [ ]
}
Clipboard icon

Update BusinessUnit as Associate

The Associate must have sufficient Permissions to perform update actions:

If a required Permission is missing, an AssociateMissingPermission error is returned.

Update BusinessUnit by ID

POST
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/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.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

id
String

id of the BusinessUnit.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
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

Update actions to be performed on the BusinessUnit.

Response:
200BusinessUnitasapplication/json
Request Example:cURL
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
Clipboard icon
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" : [ ]
}
Clipboard icon

Update BusinessUnit by Key

POST
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/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.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

key
String

key of the BusinessUnit.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
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

Update actions to be performed on the BusinessUnit.

Response:
200BusinessUnitasapplication/json
Request Example:cURL
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
Clipboard icon
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" : [ ]
}
Clipboard icon