Associate Business Units

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`
`offset` Int	Number of elements skipped. Default: `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: `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 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.
`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 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.
`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 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.
`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:

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.

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

Associate Business Units

Get BusinessUnit as Associate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get BusinessUnit by ID as Associate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get BusinessUnit by Key as Associate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Query BusinessUnits as Associate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if BusinessUnit exists as Associate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if BusinessUnit exists by ID as Associate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if BusinessUnit exists by Key as Associate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Create BusinessUnit as Associate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update BusinessUnit as Associate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update BusinessUnit by ID as Associate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update BusinessUnit by Key as Associate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get BusinessUnit as Associate

Get BusinessUnit by ID as Associate

Get BusinessUnit by Key as Associate

Query BusinessUnits as Associate

Check if BusinessUnit exists as Associate

Check if BusinessUnit exists by ID as Associate

Check if BusinessUnit exists by Key as Associate

Create BusinessUnit as Associate

Update BusinessUnit as Associate

Update BusinessUnit by ID as Associate

Update BusinessUnit by Key as Associate