Documentation
B2B

Associate Business Units

Elevate, May 20-22-2025, Miami Beach, Florida
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 as Associate

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/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 as Associate

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

BusinessUnit

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/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 as Associate

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
​
QueryPredicate
​
The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
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: true​
var.<varName>
​
String
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

BusinessUnitPagedQueryResponse

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/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 as Associate

Check if BusinessUnit exists by ID as Associate

HEAD
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units/{id}
Checks if a BusinessUnit exists with the provided 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.
associateId
​
String
​
id of the Customer who is acting on behalf of the BusinessUnit.
id
​
String
​
id of the BusinessUnit.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if BusinessUnit exists by Key as Associate

HEAD
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units/key={key}
Checks if a BusinessUnit exists with the provided 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.
associateId
​
String
​
id of the Customer who is acting on behalf of the BusinessUnit.
key
​
String
​
key of the BusinessUnit.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if BusinessUnit exists by Query Predicate as Associate

HEAD
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units
Checks if one or more BusinessUnits exist for the provided 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.
associateId
​
String
​
id of the Customer who is acting on behalf of the BusinessUnit.
Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/business-units -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

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
​
Expansion
​
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}/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
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 as Associate

The Associate must have sufficient Permissions to perform update actions:
If a required Permission is missing, an AssociateMissingPermission error is returned.
For addAssociate, setAssociates, and changeAssociate update actions, the API only accepts AssociateRoles with the buyerAssignable property set to true.

Update BusinessUnit by ID as Associate

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
​
Expansion
​
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 ConcurrentModification error will be returned.
actions​
Array of BusinessUnitUpdateAction​

Update actions to be performed on the BusinessUnit.

Response:
200

BusinessUnit

asapplication/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
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 as Associate

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
​
Expansion
​
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 ConcurrentModification error will be returned.
actions​
Array of BusinessUnitUpdateAction​

Update actions to be performed on the BusinessUnit.

Response:
200

BusinessUnit

asapplication/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
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"
}