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 | Custom Fields on the Approval Rule. |
createdAt | Date and time (UTC) the Approval Rule was initially created. |
createdBy BETA | IDs and references that created the ApprovalRule. |
lastModifiedAt | 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 in BusinessUnit
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 ApprovalRules 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 in BusinessUnit
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 in BusinessUnit
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"
}