BETA

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

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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
status

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

Defines whether the Stores of the Business Unit are set directly on the Business Unit or are inherited from a parent.

unitType

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

Parent unit of the Business Unit. Only present when the unitType is Division.

topLevelUnit

Top-level unit of the Business Unit. The top-level unit is of unitType Company.

custom

Custom Fields for the Business Unit.

createdAt

Date and time (UTC) the Business Unit was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the Business Unit was last updated.

lastModifiedByBETA

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

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

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

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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
status

Indicates whether the Business Unit can be edited and used in Orders.

Default: Active
stores

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

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

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

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

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.

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

The Customer that is part of the Business Unit.

AssociateDraft

roles
Array of AssociateRole

Roles the Associate should hold within the Business Unit.

customer

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

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

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
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
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}/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
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}/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" : [ ]
}

Update actions

Add Address

Adding an address to a Business Unit generates a BusinessUnitAddressAdded Message.

action
String
"addAddress"
address

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

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

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

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"

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"

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

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"

Defines the Type that extends the address with Custom Fields. If absent, any existing Type and Custom Fields are removed from the address.

fields

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

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"

Defines the Type that extends the BusinessUnit with Custom Fields. If absent, any existing Type and Custom Fields are removed from the BusinessUnit.

fields

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

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

Set to Explicit to specify Stores for the Business Unit. Set to FromParent to inherit Stores from a parent.

stores

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
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
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" : [ ]
}
Composable Commerce
Getting StartedMerchant CenterTutorialsHTTP APIGraphQL APIImport & ExportSDKs & Client LibrariesCustom Applications
Frontend
Getting StartedStudioDevelopingHTTP API
Sign upLog inSupportStatusOfferingTech BlogIntegrationsUser Research Program
Copyright © 2023 commercetools
Privacy PolicyImprint