Business Units

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 be organized hierarchically and can have a set of Associates assigned. Associates are represented as Customers that hold different roles, for example, Admin or Buyer. The roles are used to grant Associates different permissions.

A Business Unit can be referenced on Carts, Orders, and Quotes. With the help of Stores, Product Selections and Channels Business Units allow you to model company-specific pricing and products. Any Carts and Orders referencing a Business Unit must use the Stores, Product Selections and Channels of that Business Unit, if any are set.

Representations

BusinessUnit -Company -Division

BusinessUnitDraft -CompanyDraft -DivisionDraft

Business Unit Store Mode

BusinessUnitPagedQueryResponse

BusinessUnitReference

BusinessUnitKeyReference

BusinessUnitResourceIdentifier

BusinessUnit

Generic type to model those fields all Business Units have in common.

`id` String	Unique identifier of the Business Unit.
`version` Int	Current version of the Business Unit.
`key` String	User-defined unique identifier of the Business Unit. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`status` BusinessUnitStatus	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.
`storeMode` BusinessUnitStoreMode	Defines whether the Stores of the Business Unit are set directly on the Business Unit or are inherited from a parent.
`unitType` BusinessUnitType	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.
`associates` Array of Associate	Members that are part of the Business Unit in specific roles.
`parentUnit` BusinessUnitKeyReference	Parent unit of the Business Unit. Only present when the `unitType` is `Division`.
`topLevelUnit` BusinessUnitKeyReference	Top-level unit of the Business Unit. The top-level unit is of `unitType` `Company`.
`custom` CustomFields	Custom Fields for the Business Unit.
`createdAt` DateTime	Date and time (UTC) the Business Unit was initially created.
`createdBy`BETA CreatedBy	Present on resources created after 1 February 2019 except for events not tracked.
`lastModifiedAt` DateTime	Date and time (UTC) the Business Unit was last updated.
`lastModifiedBy`BETA LastModifiedBy	Present on resources updated after 1 February 2019 except for events not tracked.

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` BusinessUnitStoreMode	Is always `Explicit` since a Company does not have a parent Business Unit the Stores can be inherited from.
`unitType` String	`"Company"` Top-level Business Unit. Must not have a `parentUnit` defined.

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` BusinessUnitStoreMode	Defines whether the Stores of the Division are set explicitly or inherited from a parent Business Unit.
`unitType` String	`"Division"` Business Unit with a `parentUnit` reference to a Company or another Division.
`parentUnit` BusinessUnitKeyReference	Parent unit of the Division.

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 identifier for the Business Unit. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`status` BusinessUnitStatus	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` BusinessUnitStoreMode	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` BusinessUnitType	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.
`associates` Array of AssociateDraft	List of members that are part of the Business Unit in specific roles.
`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` CustomFieldsDraft	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

String

"Company"

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

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` BusinessUnitStoreMode	If not set, the Division inherits the Stores from its `parentUnit`. Set this to `Explicit` if you want to set the Stores explicitly in the `stores` field instead. Default: `FromParent`
`unitType` String	`"Division"` Business Unit with a `parentUnit` reference to a Company or another Division.
`parentUnit` BusinessUnitResourceIdentifier	The parent unit of this Division. Can be a Company or a Division.

Associate

`roles` Array of AssociateRole	Roles the Associate holds within the Business Unit.
`customer` CustomerReference	The Customer that is part of the Business Unit.

AssociateDraft

`roles` Array of AssociateRole	Roles the Associate should hold within the Business Unit.
`customer` CustomerResourceIdentifier	The Customer to be part of the Business Unit.

Associate Role

This type is equivalent to SimpleAssociateRole in the GraphQL API.

Roles defining how an Associate can interact with a Business Unit.

Admin: The Associate can update the Business Unit, create child Business Units and add or remove other Associates.
Buyer: The Associate can make purchases on behalf of the Business Unit.

Business Unit Status

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

Active: The Business Unit can be used in Orders, Carts, and Quotes and can be edited.
Inactive: The Business Unit can be edited by an Admin, but not by a Buyer. The Business Unit cannot be used in Orders, Carts, and Quotes.

Business Unit Type

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.

Business Unit Store Mode

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 first parent in the hierarchy that has Stores defined. Up to four Business Units can be set as children-of-children within a hierarchy.

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

Reference to a BusinessUnit.

`id` String	Unique identifier of the referenced BusinessUnit.
`typeId` String	`"business-unit"` References a BusinessUnit.
`obj` BusinessUnit	Contains the representation of the expanded BusinessUnit. Only present in responses to requests with Reference Expansion for BusinessUnit.

BusinessUnitKeyReference

Reference to a BusinessUnit by its key.

`key` String	Unique and immutable key of the referenced BusinessUnit.
`typeId` String	`"business-unit"` References a BusinessUnit.

BusinessUnitResourceIdentifier

ResourceIdentifier to a BusinessUnit.

`id` String	Unique identifier of the referenced BusinessUnit. Either `id` or `key` is required.
`key` String	Unique key of the referenced BusinessUnit. Either `id` or `key` is required.
`typeId` String	`"business-unit"` References a BusinessUnit.

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

Expansion

The parameter can be passed multiple times.

Response:

200BusinessUnit

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" : "some-id",
  "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" : [ ]
}

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

Expansion

The parameter can be passed multiple times.

Response:

200BusinessUnit

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" : "some-id",
  "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" : [ ]
}

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` QueryPredicate	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` Sort	The parameter can be passed multiple times.
`expand` Expansion	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 `false` to improve query performance when the `total` is not needed.

Response:

200BusinessUnitPagedQueryResponse

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" : "some-id",
    "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" : [ ],
    "storeMode" : "Explicit",
    "stores" : [ ]
  } ]
}

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

Expansion

The parameter can be passed multiple times.

Request Body:BusinessUnitDraftasapplication/json

Response:

201BusinessUnitasapplication/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" : "some-id",
  "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" : [ ]
}

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

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 409 Conflict error will be returned.
`actions` Array of BusinessUnitUpdateAction	Update actions to be performed on the BusinessUnit.

Response:

200BusinessUnitasapplication/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" : "some-id",
  "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" : [ ]
}

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

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 409 Conflict error will be returned.
`actions` Array of BusinessUnitUpdateAction	Update actions to be performed on the BusinessUnit.

Response:

200BusinessUnitasapplication/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" : "some-id",
  "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" : [ ]
}

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

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

`action` String	`"addAssociate"`
`associate` AssociateDraft	The Associate to add.

Example: json

{
  "action" : "addAssociate",
  "associate" : {
    "customer" : {
      "typeId" : "customer",
      "id" : "some-customer-id"
    },
    "roles" : [ "Admin" ]
  }
}

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` StoreResourceIdentifier	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` AssociateDraft	New version of an existing Associate.

Example: json

{
  "action" : "changeAssociate",
  "associate" : {
    "customer" : {
      "typeId" : "customer",
      "id" : "some-customer-id"
    },
    "roles" : [ "Admin" ]
  }
}

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 BusinessUnitParentUnitChanged Message.

`action` String	`"changeParentUnit"`
`parentUnit` BusinessUnitResourceIdentifier	New parent unit of the Business 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` CustomerResourceIdentifier	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 prior to when the Store was removed remain unchanged. Generates a BusinessUnitStoreRemoved Message. Only applicable when storeMode is Explicit.

`action` String	`"removeStore"`
`store` StoreResourceIdentifier	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

`action` String	`"setAddressCustomField"`
`addressId` String	ID of the address to be extended.
`name` String	Name of the Custom Field.
`value` CustomFieldValue	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" : "ExampleStringTypeField",
  "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 not provided, any existing list is removed.

Example: json

{
  "action" : "setAssociates",
  "associates" : [ {
    "customer" : {
      "typeId" : "customer",
      "id" : "some-customer-id"
    },
    "roles" : [ "Admin" ]
  }, {
    "customer" : {
      "typeId" : "customer",
      "id" : "another-customer-id"
    },
    "roles" : [ "Buyer" ]
  } ]
}

Set CustomType in Address

`action` String	`"setAddressCustomType"`
`type` TypeResourceIdentifier	Defines the Type that extends the `address` with Custom Fields. If absent, any existing Type and Custom Fields are removed from the `address`.
`fields` FieldContainer	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" : {
    "exampleStringTypeField" : "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

`action` String	`"setCustomField"`
`name` String	Name of the Custom Field.
`value` CustomFieldValue	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" : "ExampleStringTypeField",
  "value" : "TextString"
}

Set CustomType

`action` String	`"setCustomType"`
`type` TypeResourceIdentifier	Defines the Type that extends the BusinessUnit with Custom Fields. If absent, any existing Type and Custom Fields are removed from the BusinessUnit.
`fields` FieldContainer	Sets the Custom Fields for the BusinessUnit.

Example: json

{
  "action" : "setCustomType",
  "type" : {
    "id" : "{{type-id}}",
    "typeId" : "type"
  },
  "fields" : {
    "exampleStringTypeField" : "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 prior to the Set Stores update action are 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

If storeMode is changed to FromParent, current Stores defined for the Business Unit are removed. Only Business Units of type Division can be set to FromParent. This update action generates a BusinessUnitStoreModeChanged Message.

`action` String	`"setStoreMode"`
`storeMode` BusinessUnitStoreMode	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, 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` Expansion	The parameter can be passed multiple times.

Response:

200BusinessUnit

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" : "some-id",
  "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" : [ ]
}

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` Expansion	The parameter can be passed multiple times.

Response:

200BusinessUnit

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" : "some-id",
  "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" : [ ]
}

Business Units

Representations.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}.css-e0dnmk{cursor:pointer;}

BusinessUnit.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Company.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Division.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

BusinessUnitDraft.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

CompanyDraft.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

DivisionDraft.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Associate.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

AssociateDraft.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Associate Role.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Business Unit Status.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Business Unit Type.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Business Unit Store Mode.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

BusinessUnitPagedQueryResponse.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

BusinessUnitReference.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

BusinessUnitKeyReference.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

BusinessUnitResourceIdentifier.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get BusinessUnit.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get BusinessUnit by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get BusinessUnit by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Query BusinessUnits.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Create BusinessUnit.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update BusinessUnit.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update BusinessUnit by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update BusinessUnit by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update actions.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Add Address.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Add Associate.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Add Billing Address Identifier.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Add Shipping Address Identifier.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Add Store.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Change Address.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Change Associate.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Change Name.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Change Parent Unit.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Change Status.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Remove Address.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Remove Associate.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Remove Store.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Remove Billing Address Identifier.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Remove Shipping Address Identifier.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Address CustomField.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Associates.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set CustomType in Address.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Contact Email.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set CustomField.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set CustomType.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Default Billing Address.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Default Shipping Address.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Stores.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Store Mode.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete BusinessUnit.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete BusinessUnit by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete BusinessUnit by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Representations

BusinessUnit

Company

Division

BusinessUnitDraft

CompanyDraft

DivisionDraft

Associate

AssociateDraft

Associate Role

Business Unit Status

Business Unit Type

Business Unit Store Mode

BusinessUnitPagedQueryResponse

BusinessUnitReference

BusinessUnitKeyReference

BusinessUnitResourceIdentifier

Get BusinessUnit

Get BusinessUnit by ID

Get BusinessUnit by Key

Query BusinessUnits

Create BusinessUnit

Update BusinessUnit

Update BusinessUnit by ID

Update BusinessUnit by Key

Update actions

Add Address

Add Associate

Add Billing Address Identifier

Add Shipping Address Identifier

Add Store

Change Address

Change Associate

Change Name

Change Parent Unit

Change Status

Remove Address

Remove Associate

Remove Store

Remove Billing Address Identifier

Remove Shipping Address Identifier

Set Address CustomField

Set Associates

Set CustomType in Address

Set Contact Email

Set CustomField

Set CustomType

Set Default Billing Address

Set Default Shipping Address

Set Stores

Set Store Mode

Delete BusinessUnit

Delete BusinessUnit by ID

Delete BusinessUnit by Key