This feature is part of Composable Commerce for B2B and will be subject to additional terms and pricing.
Approval Rules provide a flexible approach to configuring and managing the approval process for Orders within a Business Unit.
Approval Rules can be used to define a multi-tiered approval process for B2B order management. By defining approval hierarchies using boolean logic, you can establish complex, structured approval workflows based on Associate Roles. Approval Rules are defined in tiers. Each tier contains one or more roles that are required to approve an Order before it can proceed to the next tier. You can explicitly set Approval Rules on individual Business Units. Approval Rules can also be inherited, meaning rules set on a Business Unit can be applied to other units lower in the hierarchy.
Representations
ApprovalRule
id ​String​ | Unique identifier of the Approval Rule. (identifier)​ |
version ​Int​ | Current version of the Approval Rule. |
key ​String​ | User-defined unique identifier of the Approval Rule. Must be unique within a Business Unit. MinLength:2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
name ​String​ | Name of the Approval Rule. |
description ​String​ | Description of the Approval Rule. |
status ​ | Indicates whether the Approval Rule should be matched against Orders or not. |
predicate ​String​ | The Order Predicate describing the Orders the Approval Rule should match against. |
approvers ​ | The hierarchy of approvers within the Approval Rule. |
requesters ​Array of RuleRequester​ | The Associate Roles customers must hold for their Order to require approval. MinItems:1 ​UniqueItems​ |
businessUnit ​ | The Business Unit the Approval Rule belongs to. |
custom ​CustomFields​ | Custom Fields on the Approval Rule. |
createdAt ​DateTime​ | Date and time (UTC) the Approval Rule was initially created. |
createdBy ​CreatedBy​ | IDs and references that created the ApprovalRule. (beta)​ |
lastModifiedAt ​DateTime​ | Date and time (UTC) the Approval Rule was last updated. |
lastModifiedBy ​ | IDs and references that last modified the ApprovalRule. (beta)​ |
ApprovalRuleDraft
key ​String​ | User-defined unique identifier of the Approval Rule. Uniqueness is enforced within the Business Unit. MinLength:2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
name ​String​ | Name of the Approval Rule. |
description ​String​ | Description of the Approval Rule. |
status ​ | Indicates whether the Approval Rule should be matched against Orders or not. |
predicate ​String​ | |
approvers ​ | The hierarchy of approvers within the Approval Rule. |
requesters ​Array of RuleRequesterDraft​ | The Associate Roles customers must hold for their Order to require approval. MinItems:1 ​UniqueItems​ |
ApprovalRulePagedQueryResponse
PagedQueryResult with results containing an array of ApprovalRule.
limit ​Int​ | Number of results requested. Default:20 ​Maximum: 500 ​ |
offset ​Int​ | Number of elements skipped. Maximum:10000 ​ |
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 |
results ​Array of ApprovalRule​ | Approval Rules matching the query. |
ApprovalRuleStatus
RuleRequester
associateRole ​ | The Associate Role that an Associate must hold for the Approval Rule to apply to the Orders they create. |
RuleRequesterDraft
associateRole ​ | The Associate Role that an Associate must hold for the Approval Rule to apply to the Orders they create. |
ApproverHierarchy
Describes the order in which Associates can approve the matched Order.
tiers ​Array of ApproverConjunction​ | All of the nested conjunctions must be approved in order for the hierarchy to be considered approved. MinItems:1 ​MaxItems: 5 ​ |
ApproverConjunction
and ​Array of ApproverDisjunction​ | All of the nested disjunctions must be approved in order for the conjunction to be considered approved. MinItems:1 ​ |
ApproverDisjunction
or ​Array of RuleApprover​ | Any of the nested approvers must approve in order for the disjunction to be considered approved. MinItems:1 ​ |
RuleApprover
associateRole ​ | The Associate Role that is allowed to approve at a given stage in the approval process. |
ApproverHierarchyDraft
Describes the sequence in which Associates can approve an Order.
tiers ​Array of ApproverConjunctionDraft​ | Nested conjunctions representing tiers of approvers in a hierarchy. MinItems:1 ​MaxItems: 5 ​ |
ApproverConjunctionDraft
and ​Array of ApproverDisjunctionDraft​ | All of the nested disjunctions must be approved in order for the conjunction to be considered approved. MinItems:1 ​MaxItems: 10 ​ |
ApproverDisjunctionDraft
or ​Array of RuleApproverDraft​ | Any of the nested approvers must approve in order for the disjunction to be considered approved. MinItems:1 ​ |
RuleApproverDraft
associateRole ​ | Any Associate with this Role can approve. |
Get ApprovalRule
Get ApprovalRule in BusinessUnit by ID
view_approval_rules:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
associateId String ​ |
|
businessUnitKey String ​ |
|
id String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "aba82d3f-ee7d-4a86-a4ca-adf0b2d711d0",
"version": 1,
"createdAt": "2023-02-20T16:15:51.043Z",
"lastModifiedAt": "2023-02-20T16:15:51.043Z",
"lastModifiedBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"createdBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"name": "my approval rule",
"status": "Inactive",
"predicate": "totalPrice.centAmount >= 100000",
"approvers": {
"tiers": [
{
"and": [
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead-substitute"
}
}
]
}
]
}
]
},
"requesters": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-manager"
}
}
],
"businessUnit": {
"typeId": "business-unit",
"key": "commercetools"
}
}
Get ApprovalRule in BusinessUnit by Key
view_approval_rules:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
associateId String ​ |
|
businessUnitKey String ​ |
|
key String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "aba82d3f-ee7d-4a86-a4ca-adf0b2d711d0",
"version": 1,
"createdAt": "2023-02-20T16:15:51.043Z",
"lastModifiedAt": "2023-02-20T16:15:51.043Z",
"lastModifiedBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"createdBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"name": "my approval rule",
"status": "Inactive",
"predicate": "totalPrice.centAmount >= 100000",
"approvers": {
"tiers": [
{
"and": [
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead-substitute"
}
}
]
}
]
}
]
},
"requesters": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-manager"
}
}
],
"businessUnit": {
"typeId": "business-unit",
"key": "commercetools"
}
}
Query ApprovalRule in BusinessUnit
view_approval_rules:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
associateId String ​ |
|
businessUnitKey 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. Default: 20 ​ |
offset Int ​ | Number of elements skipped. 0 |
withTotal Boolean ​ | Controls the calculation of the total number of query results. Set to Default: ​ |
ApprovalRulePagedQueryResponse
asapplication/json
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "aba82d3f-ee7d-4a86-a4ca-adf0b2d711d0",
"version": 1,
"createdAt": "2023-02-20T16:15:51.043Z",
"lastModifiedAt": "2023-02-20T16:15:51.043Z",
"lastModifiedBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"createdBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"name": "my approval rule",
"status": "Inactive",
"predicate": "totalPrice.centAmount >= 100000",
"approvers": {
"tiers": [
{
"and": [
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead-substitute"
}
}
]
}
]
}
]
},
"requesters": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-manager"
}
}
],
"businessUnit": {
"typeId": "business-unit",
"key": "commercetools"
}
}
]
}
Create ApprovalRule
Create Approval Rule in Business Unit
manage_approval_rules:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
associateId String ​ |
|
businessUnitKey String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"name" : "my approval rule",
"status" : "Inactive",
"predicate" : "totalPrice.centAmount >= 100000",
"approvers" : {
"tiers" : [ {
"and" : [ {
"or" : [ {
"associateRole" : {
"typeId" : "associate-role",
"key" : "project-team-lead"
}
}, {
"associateRole" : {
"typeId" : "associate-role",
"key" : "project-team-lead-substitute"
}
} ]
} ]
} ]
},
"requesters" : [ {
"associateRole" : {
"typeId" : "associate-role",
"key" : "project-manager"
}
} ]
}
DATA
{
"id": "aba82d3f-ee7d-4a86-a4ca-adf0b2d711d0",
"version": 1,
"createdAt": "2023-02-20T16:15:51.043Z",
"lastModifiedAt": "2023-02-20T16:15:51.043Z",
"lastModifiedBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"createdBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"name": "my approval rule",
"status": "Inactive",
"predicate": "totalPrice.centAmount >= 100000",
"approvers": {
"tiers": [
{
"and": [
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead-substitute"
}
}
]
}
]
}
]
},
"requesters": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-manager"
}
}
],
"businessUnit": {
"typeId": "business-unit",
"key": "commercetools"
}
}
Update ApprovalRule
Update ApprovalRule in BusinessUnit by ID
manage_approval_rules:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
associateId String ​ |
|
businessUnitKey String ​ |
|
id String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "setStatus",
"status" : "Active"
} ]
}
DATA
{
"id": "aba82d3f-ee7d-4a86-a4ca-adf0b2d711d0",
"version": 1,
"createdAt": "2023-02-20T16:15:51.043Z",
"lastModifiedAt": "2023-02-20T16:15:51.043Z",
"lastModifiedBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"createdBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"name": "my approval rule",
"status": "Inactive",
"predicate": "totalPrice.centAmount >= 100000",
"approvers": {
"tiers": [
{
"and": [
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead-substitute"
}
}
]
}
]
}
]
},
"requesters": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-manager"
}
}
],
"businessUnit": {
"typeId": "business-unit",
"key": "commercetools"
}
}
Update ApprovalRule in BusinessUnit by Key
manage_approval_rules:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
associateId String ​ |
|
businessUnitKey String ​ |
|
key String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "setStatus",
"status" : "Active"
} ]
}
DATA
{
"id": "aba82d3f-ee7d-4a86-a4ca-adf0b2d711d0",
"version": 1,
"createdAt": "2023-02-20T16:15:51.043Z",
"lastModifiedAt": "2023-02-20T16:15:51.043Z",
"lastModifiedBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"createdBy": {
"clientId": "U3r9iqphXgPkoWTrIsTiKAl1",
"isPlatformClient": false
},
"name": "my approval rule",
"status": "Inactive",
"predicate": "totalPrice.centAmount >= 100000",
"approvers": {
"tiers": [
{
"and": [
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "project-team-lead-substitute"
}
}
]
}
]
}
]
},
"requesters": [
{
"associateRole": {
"typeId": "associate-role",
"key": "project-manager"
}
}
],
"businessUnit": {
"typeId": "business-unit",
"key": "commercetools"
}
}
Update actions
Set Status
Setting the status for an Approval Rule generates an ApprovalRuleStatusSet Message.
action ​String​ | "setStatus" |
status ​ | New status to set for the Approval Rule. |
{
"action": "setStatus",
"status": "Active"
}
Set Name
Setting the name for an Approval Rule generates an ApprovalRuleNameSet Message.
action ​String​ | "setName" |
name ​String​ | New name to set for the Approval Rule. |
{
"action": "setName",
"name": "New name"
}
Set Description
Setting the description for an Approval Rule generates an ApprovalRuleDescriptionSet Message.
action ​String​ | "setDescription" |
description ​String​ | New description to set for the Approval Rule. |
{
"action": "setDescription",
"description": "New description"
}
Set Key
Setting the key for an Approval Rule generates an ApprovalRuleKeySet Message.
action ​String​ | "setKey" |
key ​String​ | Value to set. Must be unique within a Business Unit. If empty, any existing value will be removed. MinLength:2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
{
"action": "setKey",
"key": "new-key"
}
Set Predicate
Setting the Order Predicate for an Approval Rule generates an ApprovalRulePredicateSet Message.
action ​String​ | "setPredicate" |
predicate ​String​ | A valid Order Predicate to set for the Approval Rule. |
{
"action": "setPredicate",
"predicate": "totalPrice > \"1000.00 EUR\""
}
Set Approvers
Setting the approvers for an Approval Rule generates an ApprovalRuleApproversSet Message.
action ​String​ | "setApprovers" |
approvers ​ | New approvers to set for the Approval Rule. |
{
"action": "setApprovers",
"approvers": {
"tiers": [
{
"and": [
{
"or": [
{
"associateRole": {
"key": "approver1"
}
}
]
}
]
}
]
}
}
Set Requesters
Sets the requesters for an Approval Rule generates an ApprovalRuleRequestersSet Message.
action ​String​ | "setRequesters" |
requesters ​Array of RuleRequesterDraft​ | New requesters to set for the Approval Rule. |
{
"action": "setRequesters",
"requesters": [
{
"associateRole": {
"typeId": "associate-role",
"key": "buyer"
}
}
]
}
Set Custom Type
action ​String​ | "setCustomType" |
type ​ | Defines the Type that extends the ApprovalRule with Custom Fields. If absent, any existing Type and Custom Fields are removed from the ApprovalRule. |
fields ​ | Sets the Custom Fields fields for the ApprovalRule. |
{
"action": "setCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}
Set CustomField
action ​String​ | "setCustomField" |
name ​String​ | Name of the Custom Field. |
value ​ | If |
{
"action": "setCustomField",
"name": "exampleStringField",
"value": "TextString"
}