Documentation

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: 2​MaxLength: 256​Pattern: ^[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​
CustomFields​

Custom Fields for the AssociateRole.

createdAt​
DateTime​

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

createdBy​BETA
CreatedBy​

IDs and references that created the AssociateRole.

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the AssociateRole.

AssociateRoleDraft

key​
String​

User-defined unique identifier for the AssociateRole.

MinLength: 2​MaxLength: 256​Pattern: ^[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​
CustomFieldsDraft​

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

Reference to an AssociateRole.

id​
String​

Unique identifier of the referenced AssociateRole.

typeId​
String​
"associate-role"

References an AssociateRole.

obj​
AssociateRole​

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
​
Expansion
​
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
​
Expansion
​
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
​
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:
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
​
QueryPredicate
​
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
​
Expansion
​
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
​
Expansion
​
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​
Array of AssociateRoleUpdateAction​

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
​
Expansion
​
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​
Array of AssociateRoleUpdateAction​

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​

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​

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​
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 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"
type​
TypeResourceIdentifier​

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

fields​
FieldContainer​

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
​
Expansion
​
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
​
Expansion
​
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"
  ]
}