My Business Units

B2BB2XB2B CORE COMMERCEB2X CORE COMMERCE

The My Business Units API provides access to Business Units associated with a specific user.

For how the My Business Units API behaves and the rules that apply to it, see Me endpoints overview.
Learn more about self-service Business Unit provisioning for buyer organizations in our self-paced Model buyer organizations module.

Get My BusinessUnit

Get My BusinessUnit by ID

GET
https://api.{region}.commercetools.com/{projectKey}/me/business-units/{id}
Returns a Business Unit for a given id. Returns a 200 status if the Business Unit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
OAuth 2.0 Scopes:
manage_my_business_units:{projectKey}customer_id:{id}
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
​
String
​
Expanding a Customer reference (for example, associates[*].customer or inheritedAssociates[*].customer) is not permitted and returns an Unauthorized error.
The parameter can be passed multiple times.
Response:
200

BusinessUnit

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/me/business-units/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Get My BusinessUnit by Key

GET
https://api.{region}.commercetools.com/{projectKey}/me/business-units/key={key}
Returns a Business Unit for a given key. Returns a 200 status if the Business Unit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
OAuth 2.0 Scopes:
manage_my_business_units:{projectKey}customer_id:{id}
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
​
String
​
Expanding a Customer reference (for example, associates[*].customer or inheritedAssociates[*].customer) is not permitted and returns an Unauthorized error.
The parameter can be passed multiple times.
Response:
200

BusinessUnit

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/me/business-units/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Query My BusinessUnits

GET
https://api.{region}.commercetools.com/{projectKey}/me/business-units
Retrieves Business Units for the authenticated Customer. Returns a 200 status if successful, or a ResourceNotFound error otherwise.
OAuth 2.0 Scopes:
manage_my_business_units:{projectKey}customer_id:{id}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
The parameter can be passed multiple times.
sort
​
String
​

Use to sort query results.

For more information, see Sorting.
The parameter can be passed multiple times.
expand
​
String
​
Expanding a Customer reference (for example, associates[*].customer or inheritedAssociates[*].customer) is not permitted and returns an Unauthorized error.
The parameter can be passed multiple times.
limit
​
Int32
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int32
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​
Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.
Default: true​
var.<varName>
​
String
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

BusinessUnitPagedQueryResponse

as
application/json
Request Example:cURL
curl --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": "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": [],
      "shippingAddressIds": [],
      "billingAddressIds": [],
      "associates": [],
      "associateMode": "Explicit",
      "inheritedAssociates": [],
      "approvalRuleMode": "Explicit"
    }
  ]
}

Check if My BusinessUnit exists

Check if My BusinessUnit exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/me/business-units/{id}
Checks if a BusinessUnit exists with the provided id. Returns a 200 status if the BusinessUnit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
OAuth 2.0 Scopes:
manage_my_business_units:{projectKey}customer_id:{id}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the BusinessUnit.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/me/business-units/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if My BusinessUnit exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/me/business-units/key={key}
Checks if a BusinessUnit exists with the provided key. Returns a 200 status if the Business Unit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
OAuth 2.0 Scopes:
manage_my_business_units:{projectKey}customer_id:{id}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the BusinessUnit.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/me/business-units/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if My BusinessUnit exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/me/business-units
Checks if one or more BusinessUnits exist for the provided query predicate. Returns a 200 status if any BusinessUnits match the Query Predicate and the Customer has access to them, or a ResourceNotFound error otherwise.
OAuth 2.0 Scopes:
manage_my_business_units:{projectKey}customer_id:{id}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​
String
​

Use to filter query responses.

For more information, see Query Predicates.
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/me/business-units -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Create My BusinessUnit

POST
https://api.{region}.commercetools.com/{projectKey}/me/business-units
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.
OAuth 2.0 Scopes:
manage_my_business_units:{projectKey}customer_id:{id}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
expand
​
String
​
Expanding a Customer reference (for example, associates[*].customer or inheritedAssociates[*].customer) is not permitted and returns an Unauthorized error.
The parameter can be passed multiple times.
Request Body:MyBusinessUnitDraftasapplication/json
Response:
201

BusinessUnit

as
application/json
Request Example:cURL
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
201 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Create Associate for My BusinessUnit

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. 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.
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:MyBusinessUnitAssociateDraftasapplication/json
Response:
201

CustomerSignInResult

as
application/json
Request Example:cURL
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
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",
    "stores": [],
    "shippingAddressIds": [],
    "billingAddressIds": [],
    "customerGroupAssignments": []
  }
}

Update My BusinessUnit

Update My BusinessUnit by ID

POST
https://api.{region}.commercetools.com/{projectKey}/me/business-units/{id}
Updates a Business Unit for a given id. Returns a 200 status if the Business Unit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
OAuth 2.0 Scopes:
manage_my_business_units:{projectKey}customer_id:{id}
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
​
String
​
Expanding a Customer reference (for example, associates[*].customer or inheritedAssociates[*].customer) is not permitted and returns an Unauthorized error.
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
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 MyBusinessUnitUpdateAction​

Update actions to be performed on the BusinessUnit.

Response:
200

BusinessUnit

as
application/json
Request Example:cURL
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
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "associates": [],
  "associateMode": "Explicit",
  "inheritedAssociates": [],
  "approvalRuleMode": "Explicit"
}

Update My BusinessUnit by Key

POST
https://api.{region}.commercetools.com/{projectKey}/me/business-units/key={key}
Updates a Business Unit for a given key. Returns a 200 status if the Business Unit exists and the Customer has access to it, or a ResourceNotFound error otherwise.
OAuth 2.0 Scopes:
manage_my_business_units:{projectKey}customer_id:{id}
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
​
String
​
Expanding a Customer reference (for example, associates[*].customer or inheritedAssociates[*].customer) is not permitted and returns an Unauthorized error.
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
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 MyBusinessUnitUpdateAction​

Update actions to be performed on the BusinessUnit.

Response:
200

BusinessUnit

as
application/json
Request Example:cURL
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
200 Response Example: BusinessUnitjson
{
  "id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
  "version": 5,
  "createdAt": "2022-04-19T15:36:17.510Z",
  "lastModifiedAt": "2022-04-20T15:41:55.816Z",
  "name": "commercetools",
  "unitType": "Company",
  "key": "commercetools",
  "status": "Active",
  "storeMode": "Explicit",
  "stores": [],
  "topLevelUnit": {
    "typeId": "business-unit",
    "key": "commercetools"
  },
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "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​
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": "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 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

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

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

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

The Associate to add.

Example: json
{
  "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.

Example: json
{
  "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​
BusinessUnitResourceIdentifier​
New parent unit of the Business Unit. The new parent unit must have the same top-level unit as the old parent unit.
Example: json
{
  "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 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

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​
CustomerResourceIdentifier​
Associate to remove.
Example: json
{
  "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 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

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

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 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": "exampleStringField",
  "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​
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​
Object containing the Custom Fields fields for the address.
Required if at least one Custom Field is defined as required in the fieldDefinitions of the referenced Type.
addressId​
String​
ID of the address to be extended.
Example: json
{
  "action": "setAddressCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "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 contactEmail is absent or null, the existing contact email, if any, will be removed.
Example: json
{
  "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​
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": "exampleStringField",
  "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​
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​
Object containing the Custom Fields fields for the BusinessUnit.
Required if at least one Custom Field is defined as required in the fieldDefinitions of the referenced Type.
Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "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 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

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

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 Int​
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 Int​
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 MyBusinessUnitDraft that are used specifically for creating a Company.
unitType​
BusinessUnitType​
Company

Type of the Business Unit indicating its position in a hierarchy.

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​
BusinessUnitType​
Division

Type of the Business Unit indicating its position in a hierarchy.

parentUnit​
BusinessUnitResourceIdentifier​

The parent unit of this Division. Can be a Company or a Division.

MyBusinessUnitAssociateDraft

version​
Int64​
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​
MyCustomerDraft​
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 buyerAssignable property set to true.
MinItems: 1​