My Business Units
This feature is part of Composable Commerce for B2B and will be subject to additional terms and pricing.
The My Business Unit endpoint provides access to Business Units associated with a specific user. The endpoint requires an access token from the password 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 Customers with the AddChildUnit Permission 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 | 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 |
defaultShippingAddress Int | Index of the entry in |
billingAddresses Array of Integer | Indexes of entries in |
defaultBillingAddress Int | Index of the entry in |
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 MyBusinessUnitDraft that are used specifically for creating a Company.
unitType | "Company" Top-level Business Unit. Must not have a |
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 | "Division" Business Unit with a |
parentUnit | 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 ConcurrentModification error will be returned. |
customer | Customer to create and assign to the Business Unit. |
associateRoleAssignments Array of AssociateRoleAssignmentDraft | Roles assigned to the new Associate within a Business Unit. Can only contain AssociateRoles with the 1 |
Get BusinessUnit
Get BusinessUnit by ID
Returns a Business Unit for a given id
. Returns a 200 OK
status if the Business Unit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
manage_my_business_units:{projectKey}
customer_id:{id}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/me/business-units/{id} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc","version": 5,"createdAt": "2022-04-19T15:36:17.510Z","lastModifiedAt": "2022-04-20T15:41:55.816Z","name": "commercetools","unitType": "Company","key": "commercetools","status": "Active","storeMode": "Explicit","stores": [],"topLevelUnit": {"typeId": "business-unit","key": "commercetools"},"addresses": [],"associates": [],"associateMode": "Explicit","inheritedAssociates": [],"approvalRuleMode": "Explicit"}
Get BusinessUnit by Key
Returns a Business Unit for a given key
. Returns a 200 OK
status if the Business Unit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
manage_my_business_units:{projectKey}
customer_id:{id}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/me/business-units/key={key} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc","version": 5,"createdAt": "2022-04-19T15:36:17.510Z","lastModifiedAt": "2022-04-20T15:41:55.816Z","name": "commercetools","unitType": "Company","key": "commercetools","status": "Active","storeMode": "Explicit","stores": [],"topLevelUnit": {"typeId": "business-unit","key": "commercetools"},"addresses": [],"associates": [],"associateMode": "Explicit","inheritedAssociates": [],"approvalRuleMode": "Explicit"}
Query BusinessUnits
Returns all of the authenticated Customer’s Business Units in a Project. Returns a 200 OK
status if successful, or a ResourceNotFound error otherwise.
manage_my_business_units:{projectKey}
customer_id:{id}
region String | Region in which the Project is hosted. |
projectKey String |
|
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 | Number of results requested. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to Default: true |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/me/business-units -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"limit": 20,"offset": 0,"count": 1,"total": 1,"results": [{"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc","version": 5,"createdAt": "2022-04-19T15:36:17.510Z","lastModifiedAt": "2022-04-20T15:41:55.816Z","name": "commercetools","unitType": "Company","key": "commercetools","status": "Active","storeMode": "Explicit","stores": [],"topLevelUnit": {"typeId": "business-unit","key": "commercetools"},"addresses": [],"associates": [],"associateMode": "Explicit","inheritedAssociates": [],"approvalRuleMode": "Explicit"}]}
Check if BusinessUnit exists
Check if BusinessUnit exists by ID
Checks if a BusinessUnit exists for a given id
. Returns a 200 OK
status if the BusinessUnit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
manage_my_business_units:{projectKey}
customer_id:{id}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/me/business-units/{id} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Check if BusinessUnit exists by Key
Checks if a BusinessUnit exists for a given key
. Returns a 200 OK
status if the Business Unit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
manage_my_business_units:{projectKey}
customer_id:{id}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/me/business-units/key={key} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Check if BusinessUnit exists by Query Predicate
Checks if a BusinessUnit exists for a given Query Predicate. Returns a 200 OK
status if any BusinessUnits match the Query Predicate and the Customer has access to them, or a ResourceNotFound error otherwise.
manage_my_business_units:{projectKey}
customer_id:{id}
region String | Region in which the Project is hosted. |
projectKey String |
|
where | The parameter can be passed multiple times. |
curl --head https://api.{region}.commercetools.com/{projectKey}/me/business-units -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Create BusinessUnit
Automatically assigns the Associate to the Business Unit in the default Associate Role defined in BusinessUnitConfiguration. If there is no default Associate Role configured, this request fails with an InvalidOperation error. When creating a Division, the Associate must have the AddChildUnits
Permission in the parent unit. If the required Permission is missing, an AssociateMissingPermission error is returned.
manage_my_business_units:{projectKey}
customer_id:{id}
region String | Region in which the Project is hosted. |
projectKey String |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl 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
{"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc","version": 5,"createdAt": "2022-04-19T15:36:17.510Z","lastModifiedAt": "2022-04-20T15:41:55.816Z","name": "commercetools","unitType": "Company","key": "commercetools","status": "Active","storeMode": "Explicit","stores": [],"topLevelUnit": {"typeId": "business-unit","key": "commercetools"},"addresses": [],"associates": [],"associateMode": "Explicit","inheritedAssociates": [],"approvalRuleMode": "Explicit"}
Update BusinessUnit
To update a Business Unit using the My Business Unit endpoint, the authenticated user must be an Associate in the Business Unit with sufficient Permissions to perform the update action. If a required Permission is missing, an AssociateMissingPermission error is returned.
Update BusinessUnit by ID
Updates a Business Unit for a given id
. Returns a 200 OK
status if the Business Unit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
manage_my_business_units:{projectKey}
customer_id:{id}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the BusinessUnit on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions Array of BusinessUnitUpdateAction | Update actions to be performed on the BusinessUnit. |
application/json
curl 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
{"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc","version": 5,"createdAt": "2022-04-19T15:36:17.510Z","lastModifiedAt": "2022-04-20T15:41:55.816Z","name": "commercetools","unitType": "Company","key": "commercetools","status": "Active","storeMode": "Explicit","stores": [],"topLevelUnit": {"typeId": "business-unit","key": "commercetools"},"addresses": [],"associates": [],"associateMode": "Explicit","inheritedAssociates": [],"approvalRuleMode": "Explicit"}
Update BusinessUnit by Key
Updates a Business Unit for a given key
. Returns a 200 OK
status if the Business Unit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
manage_my_business_units:{projectKey}
customer_id:{id}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
version Int | Expected version of the BusinessUnit on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions Array of BusinessUnitUpdateAction | Update actions to be performed on the BusinessUnit. |
application/json
curl 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
{"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc","version": 5,"createdAt": "2022-04-19T15:36:17.510Z","lastModifiedAt": "2022-04-20T15:41:55.816Z","name": "commercetools","unitType": "Company","key": "commercetools","status": "Active","storeMode": "Explicit","stores": [],"topLevelUnit": {"typeId": "business-unit","key": "commercetools"},"addresses": [],"associates": [],"associateMode": "Explicit","inheritedAssociates": [],"approvalRuleMode": "Explicit"}
Update actions
Add Address
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Adding an address to a Business Unit generates a BusinessUnitAddressAdded Message.
action String | "addAddress" |
address | The address to add to |
{"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 Billing Address Identifier
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
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 |
addressKey String | Key of the address to add as a billing address. Either |
{"action": "addBillingAddressId","addressId": "{{addressId}}"}
Add Shipping Address Identifier
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
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 |
addressKey String | Key of the address to add as a shipping address. Either |
{"action": "addShippingAddressId","addressId": "{{addressId}}"}
Change Address
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Changing the address on a Business Unit generates the BusinessUnitAddressChanged Message.
action String | "changeAddress" |
addressId String | ID of the address to change. Either |
addressKey String | Key of the address to change. Either |
address | New address to set. |
{"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
Requires the UpdateAssociates
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Updating the Associate on a Business Unit generates the BusinessUnitAssociateChanged Message.
action String | "changeAssociate" |
associate | The Associate to add. |
{"action": "changeAssociate","associate": {"customer": {"typeId": "customer","id": "some-customer-id"},"associateRoleAssignments": [{"associateRole": {"typeId": "associate-role","key": "admin"},"inheritance": "Enabled"},{"associateRole": {"typeId": "associate-role","key": "buyer"}}]}}
Change Name
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Updating the name on a Business Unit generates a BusinessUnitNameChanged Message.
action String | "changeName" |
name String | New name to set. |
{"action": "changeName","name": "commercetools"}
Change Parent Unit
Requires the UpdateParentUnit
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Changing the parent of a Business Unit generates a BusinessUnitParentChanged Message.
action String | "changeParentUnit" |
parentUnit | New parent unit of the Business Unit. The new parent unit must have the same top-level unit as the old parent unit. |
{"action": "changeParentUnit","parentUnit": {"typeId": "business-unit","key": "commercetools"}}
Remove Address
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Removing the address from a Business Unit generates the BusinessUnitAddressRemoved Message.
action String | "removeAddress" |
addressId String | ID of the address to be removed. Either |
addressKey String | Key of the address to be removed. Either |
{"action": "removeAddress","addressId": "{{addressId}}"}
Remove Associate
Requires the UpdateAssociates
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Removing an Associate from a Business Unit generates a BusinessUnitAssociateRemoved Message.
action String | "removeAssociate" |
customer | Associate to remove. |
{"action": "removeAssociate","customer": {"typeId": "customer","id": "some-customer-id"}}
Remove Billing Address Identifier
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
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 |
addressKey String | Key of the billing address to be removed. Either |
{"action": "removeBillingAddressId","addressId": "{{addressId}}"}
Remove Shipping Address Identifier
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
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 |
addressKey String | Key of the shipping address to be removed. Either |
{"action": "removeShippingAddressId","addressId": "{{addressId}}"}
Set Address CustomField
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Adding a Custom Field to an Address of a Business Unit generates the BusinessUnitAddressCustomFieldAdded Message, removing one generates the BusinessUnitAddressCustomFieldRemoved Message, and updating an existing one generates the BusinessUnitAddressCustomFieldChanged Message.
action String | "setAddressCustomField" |
addressId String | ID of the |
name String | Name of the Custom Field. |
value | If |
{"action": "setAddressCustomField","name": "ExampleStringTypeField","value": "TextString","addressId": "{{address-id}}"}
Set Custom Type in Address
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Adding or updating a Custom Type to an Address of a Business Unit generates the BusinessUnitAddressCustomTypeSet Message, and removing one generates the BusinessUnitAddressCustomTypeRemoved Message.
action String | "setAddressCustomType" |
type | Defines the Type that extends the |
fields | Sets the Custom Fields fields for the |
addressId String | ID of the |
{"action": "setAddressCustomType","type": {"id": "{{type-id}}","typeId": "type"},"fields": {"exampleStringTypeField": "TextString"},"addressId": "{{address-id}}"}
Set ContactEmail
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Setting the contact email on a Business Unit generates a BusinessUnitContactEmailSet Message.
action String | "setContactEmail" |
contactEmail String | Email to set.
If |
{"action": "setContactEmail","contactEmail": "contact@example.com"}
Set CustomField
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Adding a Custom Field to a Business Unit generates the BusinessUnitCustomFieldAdded Message, removing one generates the BusinessUnitCustomFieldRemoved Message, and updating an existing one generates the BusinessUnitCustomFieldChanged Message.
action String | "setCustomField" |
name String | Name of the Custom Field. |
value | If |
{"action": "setCustomField","name": "ExampleStringTypeField","value": "TextString"}
Set Custom Type
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
Adding or updating a Custom Type on a Business Unit generates the BusinessUnitCustomTypeSet Message, removing one generates the BusinessUnitCustomTypeRemoved Message.
action String | "setCustomType" |
type | 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. |
{"action": "setCustomType","type": {"id": "{{type-id}}","typeId": "type"},"fields": {"exampleStringTypeField": "TextString"}}
Set Default Billing Address ID
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
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 |
addressKey String | Key of the address to add as a billing address. Either |
{"action": "setDefaultBillingAddress","addressId": "{{addressId}}"}
Set Default Shipping Address ID
Requires the UpdateBusinessUnitDetails
Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
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 |
addressKey String | Key of the address to add as a shipping address. Either |
{"action": "setDefaultShippingAddress","addressId": "{{addressId}}"}
Create Associate for a BusinessUnit by Key
The My Business Unit endpoint does not support assigning existing Customers to a Business Unit.
Associates with the UpdateAssociates
Permission can use this endpoint to create a new Customer and associate it with the Business Unit.
If the required Permission is missing, an AssociateMissingPermission error is returned.
manage_my_business_units:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
businessUnitKey String |
|
application/json
application/json
curl 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"},"associateRoleAssignments" : [ {"associateRole" : {"key" : "buyer-role"}} ]}DATA
{"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","stores": []}}