Associate Roles

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

Associate Roles give Associates controlled access to Business Units, Carts, Orders, Quotes, and Quote Requests.

Associate Roles provide a way to group granular Permissions and assign them to Associates within a Business Unit.

Representations

AssociateRole

id
String

Unique identifier of the AssociateRole.

version
Int

Current version of the AssociateRole.

key
String

User-defined unique identifier of the AssociateRole.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
buyerAssignable
Boolean

Whether the AssociateRole can be assigned to an Associate by a buyer. If false, the AssociateRole can only be assigned using the general endpoint.

Default: true
name
String

Name of the AssociateRole.

permissions
Array of Permission

List of Permissions for the AssociateRole.

custom

Custom Fields for the AssociateRole.

createdAt

Date and time (UTC) the AssociateRole was initially created.

createdByBETA

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

lastModifiedAt

Date and time (UTC) the AssociateRole was last updated.

lastModifiedByBETA

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

AssociateRoleDraft

key
String

User-defined unique identifier for the AssociateRole.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
name
String

Name of the AssociateRole.

buyerAssignable
Boolean

Whether the AssociateRole can be assigned to an Associate by a buyer.

Default: true
permissions
Array of Permission

List of Permissions for the AssociateRole.

custom

Custom Fields for the AssociateRole.

Permission

Permissions grant granular access to Approval Rules, Approval Flows, Business Units, Carts, Orders, Quotes, and Quote Requests.

Approval Flow Permissions

UpdateApprovalFlows

An Associate can update Approval Flows.

Approval Rule Permissions

CreateApprovalRules

An Associate can create Approval Rules.

UpdateApprovalRules

An Associate can update Approval Rules.

Business Unit Permissions

AddChildUnits

An Associate can create a child Business Unit.

UpdateAssociates

An Associate can manage other Associates.

UpdateBusinessUnitDetails

An Associate can edit Business Unit details.

UpdateParentUnit

An Associate can assign a Business Unit to be the parent unit. Additionally, the Associate requires the AddChildUnits permission in the new parent to perform the assignment.

Cart Permissions

CreateMyCarts

An Associate can create their own B2B Carts.

CreateOthersCarts

An Associate can create B2B Carts that belong to other Associates.

DeleteMyCarts

An Associate can delete their own B2B Carts.

DeleteOthersCarts

An Associate can delete B2B Carts that belong to other Associates.

UpdateMyCarts

An Associate can update their own B2B Carts.

UpdateOthersCarts

An Associate can update B2B Carts that belong to other Associates.

ViewMyCarts

An Associate can view their own B2B Carts.

ViewOthersCarts

An Associate can view B2B Carts that belong to other Associates.

Order Permissions

CreateMyOrdersFromMyCarts

An Associate can create Orders from their own B2B Carts.

CreateMyOrdersFromMyQuotes

An Associate can create Orders from their own B2B Quotes.

CreateOrdersFromOthersCarts

An Associate can create Orders from B2B Carts that belong to other Associates.

CreateOrdersFromOthersQuotes

An Associate can create Orders from B2B Quotes that belong to other Associates.

UpdateMyOrders

An Associate can update their own B2B Orders.

UpdateOthersOrders

An Associate can update B2B Orders that belong to other Associates.

ViewMyOrders

An Associate can view their own B2B Orders.

ViewOthersOrders

An Associate can view B2B Orders that belong to other Associates.

Quote Permissions

AcceptMyQuotes

An Associate can accept their own B2B Quotes.

AcceptOthersQuotes

An Associate can accept B2B Quotes that belong to other Associates.

DeclineMyQuotes

An Associate can decline their own B2B Quotes.

DeclineOthersQuotes

An Associate can decline B2B Quotes that belong to other Associates.

ReassignMyQuotes

An Associate can reassign their own B2B Quotes to a different Associate.

ReassignOthersQuotes

An Associate can reassign B2B Quotes that belong to other Associates.

RenegotiateMyQuotes

An Associate can renegotiate their own B2B Quotes.

RenegotiateOthersQuotes

An Associate can renegotiate B2B Quotes that belong to other Associates.

ViewMyQuotes

An Associate can view their own B2B Quotes.

ViewOthersQuotes

An Associate can view B2B Quotes that belong to other Associates.

Quote Request Permissions

CreateMyQuoteRequestsFromMyCarts

An Associate can create their own Quote Requests from their own B2B Carts.

CreateQuoteRequestsFromOthersCarts

An Associate can create Quote Requests from B2B Carts that belong to other Associates.

UpdateMyQuoteRequests

An Associate can update their own B2B Quote Requests.

UpdateOthersQuoteRequests

An Associate can update B2B Quote Requests of other Associates.

ViewMyQuoteRequests

An Associate can view their own B2B Quote Requests.

ViewOthersQuoteRequests

An Associate can view B2B Quote Requests that belong to other Associates.

AssociateRolePagedQueryResponse

PagedQueryResult with results containing an array of AssociateRole.

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 AssociateRole

AssociateRoles matching the query.

AssociateRoleReference

id
String

Unique identifier of the referenced AssociateRole.

typeId
String
"associate-role"

References an AssociateRole.

obj

Contains the representation of the expanded AssociateRole. Only present in responses to requests with Reference Expansion for AssociateRole.

AssociateRoleKeyReference

Reference to an AssociateRole by its key.

key
String

Unique and immutable key of the referenced AssociateRole.

typeId
String
"associate-role"

References an AssociateRole.

AssociateRoleResourceIdentifier

ResourceIdentifier of an AssociateRole. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

id
String

Unique identifier of the referenced AssociateRole. Required if key is absent.

key
String

Unique key of the referenced AssociateRole. Required if id is absent.

typeId
String
"associate-role"

References an AssociateRole.

Get AssociateRole

Get AssociateRole by ID

GET
https://api.{region}.commercetools.com/{projectKey}/associate-roles/{id}
OAuth 2.0 Scopes:
view_associate_roles:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the AssociateRole.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200AssociateRoleasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/associate-roles/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: AssociateRolejson
{
"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version": 5,
"createdAt": "2022-04-19T15:36:17.510Z",
"lastModifiedAt": "2022-04-20T15:41:55.816Z",
"name": "Regional Manager",
"key": "regional-manager",
"buyerAssignable": true,
"permissions": [
"UpdateOthersCarts",
"UpdateMyQuoteRequests",
"UpdateOthersOrders",
"ViewOthersCarts",
"ViewOthersOrders",
"ViewOthersQuoteRequests"
]
}

Get AssociateRole by Key

GET
https://api.{region}.commercetools.com/{projectKey}/associate-roles/key={key}
OAuth 2.0 Scopes:
view_associate_roles:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the AssociateRole.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200AssociateRoleasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/associate-roles/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: AssociateRolejson
{
"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version": 5,
"createdAt": "2022-04-19T15:36:17.510Z",
"lastModifiedAt": "2022-04-20T15:41:55.816Z",
"name": "Regional Manager",
"key": "regional-manager",
"buyerAssignable": true,
"permissions": [
"UpdateOthersCarts",
"UpdateMyQuoteRequests",
"UpdateOthersOrders",
"ViewOthersCarts",
"ViewOthersOrders",
"ViewOthersQuoteRequests"
]
}

Query AssociateRoles

GET
https://api.{region}.commercetools.com/{projectKey}/associate-roles
OAuth 2.0 Scopes:
view_associate_roles:{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:
200AssociateRolePagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/associate-roles -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: AssociateRolePagedQueryResponsejson
{
"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": "Regional Manager",
"key": "regional-manager",
"buyerAssignable": true,
"permissions": [
"UpdateOthersCarts",
"UpdateMyQuoteRequests",
"UpdateOthersOrders",
"ViewOthersCarts",
"ViewOthersOrders",
"ViewOthersQuoteRequests"
]
}
]
}

Check if AssociateRole exists

Check if AssociateRole exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/associate-roles/{id}

Checks if an AssociateRole exists for a given id. Returns a 200 OK status if the AssociateRole exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_associate_roles:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the AssociateRole.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/associate-roles/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if AssociateRole exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/associate-roles/key={key}

Checks if an AssociateRole exists for a given key. Returns a 200 OK status if the AssociateRole exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_associate_roles:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the AssociateRole.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/associate-roles/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if AssociateRole exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/associate-roles

Checks if an AssociateRole exists for a given Query Predicate. Returns a 200 OK status if any AssociateRole match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_associate_roles:{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.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/associate-roles -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create AssociateRole

POST
https://api.{region}.commercetools.com/{projectKey}/associate-roles

Creating a Associate Role generates the AssociateRoleCreated Message.

OAuth 2.0 Scopes:
manage_associate_roles:{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:AssociateRoleDraftasapplication/json
Response:
201AssociateRoleasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/associate-roles -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"key" : "regional-manager",
"permissions" : [ "ViewMyCarts", "UpdateMyCarts" ]
}
DATA
201 Response Example: AssociateRolejson
{
"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version": 5,
"createdAt": "2022-04-19T15:36:17.510Z",
"lastModifiedAt": "2022-04-20T15:41:55.816Z",
"name": "Regional Manager",
"key": "regional-manager",
"buyerAssignable": true,
"permissions": [
"UpdateOthersCarts",
"UpdateMyQuoteRequests",
"UpdateOthersOrders",
"ViewOthersCarts",
"ViewOthersOrders",
"ViewOthersQuoteRequests"
]
}

Update AssociateRole

Update AssociateRole by ID

POST
https://api.{region}.commercetools.com/{projectKey}/associate-roles/{id}
OAuth 2.0 Scopes:
manage_associate_roles:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the AssociateRole.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the AssociateRole on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions

Update actions to be performed on the AssociateRole.

Response:
200AssociateRoleasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/associate-roles/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 3,
"actions" : [ {
"action" : "setName",
"name" : "regional-manager"
} ]
}
DATA
200 Response Example: AssociateRolejson
{
"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version": 5,
"createdAt": "2022-04-19T15:36:17.510Z",
"lastModifiedAt": "2022-04-20T15:41:55.816Z",
"name": "Regional Manager",
"key": "regional-manager",
"buyerAssignable": true,
"permissions": [
"UpdateOthersCarts",
"UpdateMyQuoteRequests",
"UpdateOthersOrders",
"ViewOthersCarts",
"ViewOthersOrders",
"ViewOthersQuoteRequests"
]
}

Update AssociateRole by Key

POST
https://api.{region}.commercetools.com/{projectKey}/associate-roles/key={key}
OAuth 2.0 Scopes:
manage_associate_roles:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the AssociateRole.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
application/json
version
Int

Expected version of the AssociateRole on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions

Update actions to be performed on the AssociateRole.

Response:
200AssociateRoleasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/associate-roles/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 3,
"actions" : [ {
"action" : "setName",
"name" : "regional-manager"
} ]
}
DATA
200 Response Example: AssociateRolejson
{
"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version": 5,
"createdAt": "2022-04-19T15:36:17.510Z",
"lastModifiedAt": "2022-04-20T15:41:55.816Z",
"name": "Regional Manager",
"key": "regional-manager",
"buyerAssignable": true,
"permissions": [
"UpdateOthersCarts",
"UpdateMyQuoteRequests",
"UpdateOthersOrders",
"ViewOthersCarts",
"ViewOthersOrders",
"ViewOthersQuoteRequests"
]
}

Update actions

Add Permission

Adding a Permission to an AssociateRole generates an AssociateRolePermissionAdded Message.

action
String
"addPermission"
permission

Permission to be added to the AssociateRole.

Example: json
{
"action": "addPermission",
"permission": "ViewMyCarts"
}

Change BuyerAssignable

Changing the buyerAssignable value of an AssociateRole generates an AssociateRoleBuyerAssignableChanged Message.

action
String
"changeBuyerAssignable"
buyerAssignable
Boolean

The new value of the buyerAssignable field of the AssociateRole.

Example: json
{
"action": "changeBuyerAssignable",
"buyerAssignable": false
}

Remove Permission

Removing a Permission from an AssociateRole generates an AssociateRolePermissionRemoved Message.

action
String
"removePermission"
permission

Permission to be removed from the AssociateRole.

Example: json
{
"action": "removePermission",
"permission": "ViewMyCarts"
}

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 InvalidOperationError error. If value is provided, it is set for the field defined by name.

Example: json
{
"action": "setCustomField",
"name": "ExamplaryStringTypeField",
"value": "TextString"
}

Set Custom Type

action
String
"setCustomType"

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

fields

Sets the Custom Fields for the AssociateRole.

Example: json
{
"action": "setCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"examplaryStringTypeField": "TextString"
}
}

Set Name

Updating the name of an AssociateRole generates an AssociateRoleNameSet Message.

action
String
"setName"
name
String

New name to set. If name is absent or null, the existing name, if any, will be removed.

Example: json
{
"action": "setName",
"name": "regional-manager"
}

Set Permissions

Updating the Permissions on an AssociateRole generates an AssociateRolePermissionsSet Message.

action
String
"setPermissions"
permissions
Array of Permission

Overrides the current list of Permissions for the AssociateRole.

Example: json
{
"action": "setPermissions",
"permissions": ["ViewMyCarts", "ViewOthersCarts"]
}

Delete AssociateRole

Delete AssociateRole by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/associate-roles/{id}
OAuth 2.0 Scopes:
manage_associate_roles:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the AssociateRole.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:
200AssociateRoleasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/associate-roles/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: AssociateRolejson
{
"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version": 5,
"createdAt": "2022-04-19T15:36:17.510Z",
"lastModifiedAt": "2022-04-20T15:41:55.816Z",
"name": "Regional Manager",
"key": "regional-manager",
"buyerAssignable": true,
"permissions": [
"UpdateOthersCarts",
"UpdateMyQuoteRequests",
"UpdateOthersOrders",
"ViewOthersCarts",
"ViewOthersOrders",
"ViewOthersQuoteRequests"
]
}

Delete AssociateRole by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/associate-roles/key={key}

Deleting an AssociateRole generates the AssociateRoleDeleted Message. An AssociateRole can only be deleted if it is not assigned to any Associates.

OAuth 2.0 Scopes:
manage_associate_roles:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the AssociateRole.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:
200AssociateRoleasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/associate-roles/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: AssociateRolejson
{
"id": "2a3baa00-44fa-4ab8-bec7-933c31e18dcc",
"version": 5,
"createdAt": "2022-04-19T15:36:17.510Z",
"lastModifiedAt": "2022-04-20T15:41:55.816Z",
"name": "Regional Manager",
"key": "regional-manager",
"buyerAssignable": true,
"permissions": [
"UpdateOthersCarts",
"UpdateMyQuoteRequests",
"UpdateOthersOrders",
"ViewOthersCarts",
"ViewOthersOrders",
"ViewOthersQuoteRequests"
]
}