Documentation
BETA

My Business Unit

This feature is part of Composable Commerce for B2B and will be subject to additional terms and pricing.

The My Business Unit endpoint creates and provides access to Business Units associated with a specific user. The endpoint requires an access token from the password flow or anonymous session flow.

A Business Unit created using the My Business Unit endpoint is Inactive by default. Additionally, there is a restriction on updating Business Unit status using the My Business Unit endpoint. This ensures that a merchant can inspect a Business Unit created by a Customer, assign the appropriate Products and Prices, and activate it only when it is ready to be used. You can change this default configuration through a Project-level setting.

My Business Unit allows Admin Customers to create new Business Units and edit their existing ones. New Customers can also sign-up and create and manage new Business Units.

The My Business Unit endpoint does not support managing the Stores of a Business Unit, changing the Business Unit status, or assigning new Associates. This intentional restriction provides additional security in scenarios when the client application must communicate directly with the Composable Commerce API, for example in the case of mobile applications. If you need to update a field available only on the full Business Unit resource, do so from a trusted, server-side application.

A checkout flow that uses My Business Unit, My Cart, and My Order endpoints has additional limitations. For example, the use of external prices or external taxes is not supported.

Representations

MyBusinessUnitDraft

key​
String​

User-defined unique identifier for the BusinessUnit.

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

defaultShipingAddress​
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​
CustomFields​

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 MyBusinessUnitDraft 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 the Company or a higher order Division. Contains the fields and values of the generic MyBusinessUnitDraft that are used specifically for creating a Division.

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.

MyBusinessUnitAssociateDraft

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.

customer​
MyCustomerDraft​

Customer to create and assign to the Business Unit.

Get BusinessUnit

Get BusinessUnit by ID

GET
https://api.{region}.commercetools.com/{projectKey}/me/business-units/{id}
OAuth 2.0 Scopes:
manage_my_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 -X GET https://api.{region}.commercetools.com/{projectKey}/me/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}/me/business-units/key={key}
OAuth 2.0 Scopes:
manage_my_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 -X GET https://api.{region}.commercetools.com/{projectKey}/me/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}/me/business-units
OAuth 2.0 Scopes:
manage_my_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 -X GET https://api.{region}.commercetools.com/{projectKey}/me/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",
    "storeMode" : "Explicit",
    "stores" : [ ],
    "topLevelUnit" : {
      "typeId" : "business-unit",
      "key" : "commercetools"
    },
    "addresses" : [ ],
    "associates" : [ ]
  } ]
}

Create BusinessUnit

Creating a Business Unit using the My Business Unit endpoint automatically assigns the authenticated user to the Business Unit in the Associate Roles of Admin as well as Buyer.

POST
https://api.{region}.commercetools.com/{projectKey}/me/business-units
OAuth 2.0 Scopes:
manage_my_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:MyBusinessUnitDraft
Response:

201BusinessUnit

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/me/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

To update a Business Unit using the My Business Unit endpoint, the authenticated user must be an Associate with the Admin role in the Business Unit.

Update BusinessUnit by ID

POST
https://api.{region}.commercetools.com/{projectKey}/me/business-units/{id}
OAuth 2.0 Scopes:
manage_my_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:
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:

200BusinessUnit

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/me/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}/me/business-units/key={key}
OAuth 2.0 Scopes:
manage_my_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:
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:

200BusinessUnit

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/me/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​
BaseAddress​

The address to add to addresses.

Example: json
{
  "action" : "addAddress",
  "address" : {
    "id" : "exampleAddress",
    "key" : "exampleKey",
    "title" : "My Address",
    "salutation" : "Mr.",
    "firstName" : "Example",
    "lastName" : "Person",
    "streetName" : "Examplary 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 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}}"
}

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" : "Examplary 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​

The Associate to add.

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. The user must be an Associate with the Admin role in the new parent unit.

action​
String​
"changeParentUnit"
parentUnit​
BusinessUnitResourceIdentifier​

New parent unit of the Business Unit.

Example: json
{
  "action" : "changeParentUnit",
  "parentUnit" : {
    "typeId" : "business-unit",
    "key" : "commercetools"
  }
}

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 Billing Address Identifier

Removing a billing address from a Business Unit generates a BusinessUnitBillingAddressRemoved Message.

action​
String​
"removeBillingAddressId"
addressId​
String​

ID of the billing address to be removed. Either addressId or addressKey is required.

addressKey​
String​

Key of the billing address to be removed. 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 shipping address to be removed. Either addressId or addressKey is required.

addressKey​
String​

Key of the shipping address to be removed. 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" : "ExamplaryStringTypeField",
  "value" : "TextString",
  "addressId" : "{{address-id}}"
}

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 fields for the address.

addressId​
String​

ID of the address to be extended.

Example: json
{
  "action" : "setAddressCustomType",
  "type" : {
    "id" : "{{type-id}}",
    "typeId" : "type"
  },
  "fields" : {
    "examplaryStringTypeField" : "TextString"
  },
  "addressId" : "{{address-id}}"
}

Set ContactEmail

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" : "ExamplaryStringTypeField",
  "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" : {
    "examplaryStringTypeField" : "TextString"
  }
}

Set Default Billing Address ID

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 ID

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

Create Associate for a BusinessUnit by Key

POST
https://api.{region}.commercetools.com/{projectKey}/in-business-unit/key={businessUnitKey}/me/customers

The My Business Unit endpoint does not support assigning existing Customers to a Business Unit. Use this endpoint to create a new Customer and associate it with the Business Unit. The user must have the Admin role within the Business Unit to perform this request. The new Customer is created with an empty set of roles.

OAuth 2.0 Scopes:
manage_my_business_units:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

businessUnitKey
​
String
​

key of the BusinessUnit.

Request Body:MyBusinessUnitAssociateDraft
Response:

201CustomerSignInResult

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/in-business-unit/key={businessUnitKey}/me/customers -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 2,
  "customer" : {
    "email" : "<random>@example.com",
    "password" : "secret123",
    "firstName" : "John",
    "lastName" : "Doe"
  }
}
DATA
201 Response Example: CustomerSignInResultjson
{
  "customer" : {
    "addresses" : [ ],
    "email" : "johndoe@example.com",
    "firstName" : "John",
    "id" : "some_123_id",
    "isEmailVerified" : false,
    "lastName" : "Doe",
    "password" : "****aGg=",
    "version" : 1,
    "createdAt" : "2015-07-06T13:22:33.339Z",
    "lastModifiedAt" : "2015-07-06T13:22:33.339Z",
    "authenticationMode" : "Password"
  }
}