Approval Rules provide a flexible approach to configuring and managing the approval process for Orders within a Business Unit.
Representations
ApprovalRule
id ​String​ | Unique identifier of the Approval Rule. |
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: true ​ |
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 ​BETACreatedBy​ | IDs and references that created the ApprovalRule. |
lastModifiedAt ​DateTime​ | Date and time (UTC) the Approval Rule was last updated. |
lastModifiedBy ​BETA | IDs and references that last modified the ApprovalRule. |
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: true ​ |
ApprovalRulePagedQueryResponse
limit ​Int​ | Number of results requested. Default: 20 ​Minimum: 0 ​Maximum: 500 ​ |
offset ​Int​ | Number of elements skipped. Default: 0 ​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 withTotal=false .
When the results are filtered with a Query Predicate, total is subject to a limit. |
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
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
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 ​ | key of the Project. |
associateId String ​ | |
businessUnitKey String ​ | key of the BusinessUnit. |
id String ​ | id of the ApprovalRule. |
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 ​ | key of the Project. |
associateId String ​ | |
businessUnitKey String ​ | key of the BusinessUnit. |
key String ​ | key of the ApprovalRule. |
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 ​ | key of the Project. |
associateId String ​ | |
businessUnitKey String ​ | key of the BusinessUnit. |
where | 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 ​Minimum: 0 ​Maximum: 500 ​ |
offset Int ​ | 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. |
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 ​ | key of the Project. |
associateId String ​ | |
businessUnitKey String ​ | key of the BusinessUnit. |
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 ​ | key of the Project. |
associateId String ​ | |
businessUnitKey String ​ | key of the BusinessUnit. |
id String ​ | id of the ApprovalRule. |
expand | The parameter can be passed multiple times. |
application/json
version ​Int​ | Expected version of the ApprovalRule to 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 ApprovalRuleUpdateAction​ | Update actions to be performed on the ApprovalRule. |
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 ​ | key of the Project. |
associateId String ​ | |
businessUnitKey String ​ | key of the BusinessUnit. |
key String ​ | key of the ApprovalRule. |
expand | The parameter can be passed multiple times. |
application/json
version ​Int​ | Expected version of the ApprovalRule to 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 ApprovalRuleUpdateAction​ | Update actions to be performed on the ApprovalRule. |
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
action ​String​ | "setStatus" |
status ​ | New status to set for the Approval Rule. |
{
"action": "setStatus",
"status": "Active"
}
Set Name
action ​String​ | "setName" |
name ​String​ | New name to set for the Approval Rule. |
{
"action": "setName",
"name": "New name"
}
Set Description
action ​String​ | "setDescription" |
description ​String​ | New description to set for the Approval Rule. |
{
"action": "setDescription",
"description": "New description"
}
Set Key
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
action ​String​ | "setPredicate" |
predicate ​String​ | A valid Order Predicate to set for the Approval Rule. |
{
"action": "setPredicate",
"predicate": "totalPrice > \"1000.00 EUR\""
}
Set Approvers
action ​String​ | "setApprovers" |
approvers ​ | New approvers to set for the Approval Rule. |
{
"action": "setApprovers",
"approvers": {
"tiers": [
{
"and": [
{
"or": [
{
"associateRole": {
"key": "approver1"
}
}
]
}
]
}
]
}
}
Set Requesters
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 value is absent or null , this field will be removed if it exists.
Removing a field that does not exist returns an InvalidOperation error.
If value is provided, it is set for the field defined by name . |
{
"action": "setCustomField",
"name": "exampleStringField",
"value": "TextString"
}