Approval Flows represent the entire approval process for an Order within a Business Unit and contain information about the status of approvals, rejections, and the Associates involved in the process.
Representations
ApprovalFlow
id ​String​ | Unique identifier of the Approval Flow. |
version ​Int​ | Current version of the Approval Flow. |
order ​ | Order that needs to be approved. |
businessUnit ​ | Business Unit the Approval Flow belongs to. |
rules ​Array of ApprovalRule​ | Approval Rules that matched the Order. |
status ​ | Indicates whether the Approval Flow is under review, approved, or rejected. Default:ÂPending ​ |
rejection ​ | Present when the status of the Approval Flow is Rejected . |
approvals ​Array of ApprovalFlowApproval​ | Existing approvals in the Approval Flow. |
eligibleApprovers ​Array of RuleApprover​ | Associate Roles that can approve according to the approver hierarchy tiers defined in rules .
Associates are allowed to reject even after they have given approval, as long as the current approver hierarchy tier still contains their role. |
pendingApprovers ​Array of RuleApprover​ | Associate Roles required for approval based on the approver hierarchy tiers defined in rules across all remaining tiers. |
currentTierPendingApprovers ​Array of RuleApprover​ | Associate Roles required for approval based on the approver hierarchy tiers defined in rules only for the currently active tier(s). |
custom ​CustomFields​ | Custom Fields on the Approval Flow. |
createdAt ​DateTime​ | Date and time (UTC) the Approval Flow was initially created. |
createdBy ​BETACreatedBy​ | IDs and references that created the ApprovalFlow. |
lastModifiedAt ​DateTime​ | Date and time (UTC) the Approval Flow was last updated. |
lastModifiedBy ​BETA | IDs and references that last modified the ApprovalFlow. |
ApprovalFlowPagedQueryResponse
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 ApprovalFlow​ | Approval Flows matching the query. |
ApprovalFlowStatus
Pending
Default status of Approval Flows, indicating that the Approval Flow has not been fully approved or rejected.
Approved
Automatically set when all approvers from matching Approval Rules have approved. It indicates that the Approval Flow has been fully approved and is completed.
Rejected
Automatically set when a rejection occurs in the Approval Flow. A single rejection is sufficient to reject the entire Approval Flow.
ApprovalFlowRejection
rejecter ​Associate​ | Associate who rejected the Approval Flow. |
rejectedAt ​DateTime​ | Date and time (UTC) the Approval Flow was rejected. |
reason ​String​ | The reason for the rejection of the Approval Flow. |
ApprovalFlowApproval
approver ​Associate​ | Associate who approved the Approval Flow. |
approvedAt ​DateTime​ | Date and time (UTC) the Approval Flow was approved. |
Get ApprovalFlow
Get ApprovalFlow in BusinessUnit by ID
view_approval_flows:{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 ApprovalFlow. |
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-flows/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "0bd46ab0-ab12-4191-be2a-749e4f0453ef",
"version": 2,
"createdAt": "2023-06-12T14:43:46.096Z",
"lastModifiedAt": "2023-06-12T14:43:46.202Z",
"lastModifiedBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"createdBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"order": {
"typeId": "order",
"id": "f6c6cd95-0a09-4dd6-9253-1cd27c70b184"
},
"businessUnit": {
"typeId": "business-unit",
"key": "bu-key"
},
"rules": [
{
"id": "ff806a85-1457-4cef-929a-79aefe85f02d",
"version": 1,
"createdAt": "2023-06-12T14:43:45.732Z",
"lastModifiedAt": "2023-06-12T14:43:45.732Z",
"lastModifiedBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"createdBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"key": "ar-key",
"name": "name",
"description": "description",
"status": "Active",
"predicate": "customer.email = \"example@example.org\"",
"approvers": {
"tiers": [
{
"and": [
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver0"
}
}
]
},
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver1"
}
}
]
}
]
},
{
"and": [
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver2"
}
}
]
}
]
}
]
},
"requesters": [
{
"associateRole": {
"typeId": "associate-role",
"key": "requester"
}
}
],
"businessUnit": {
"typeId": "business-unit",
"key": "bu-key"
}
}
],
"status": "Pending",
"approvals": [
{
"approver": {
"customer": {
"typeId": "customer",
"id": "9c95aece-ccfa-4cc2-98c5-6b7a5e474361"
},
"associateRoleAssignments": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver0"
},
"inheritance": "Disabled"
}
]
},
"approvedAt": "2023-04-06T17:41:28.123Z"
}
],
"eligibleApprovers": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver0"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "approver1"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "approver2"
}
}
],
"pendingApprovers": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver1"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "approver2"
}
}
],
"currentTierPendingApprovers": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver1"
}
}
]
}
Query ApprovalFlow in BusinessUnit
view_approval_flows:{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. |
ApprovalFlowPagedQueryResponse
asapplication/json
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-flows -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "0bd46ab0-ab12-4191-be2a-749e4f0453ef",
"version": 2,
"createdAt": "2023-06-12T14:43:46.096Z",
"lastModifiedAt": "2023-06-12T14:43:46.202Z",
"lastModifiedBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"createdBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"order": {
"typeId": "order",
"id": "f6c6cd95-0a09-4dd6-9253-1cd27c70b184"
},
"businessUnit": {
"typeId": "business-unit",
"key": "bu-key"
},
"rules": [
{
"id": "ff806a85-1457-4cef-929a-79aefe85f02d",
"version": 1,
"createdAt": "2023-06-12T14:43:45.732Z",
"lastModifiedAt": "2023-06-12T14:43:45.732Z",
"lastModifiedBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"createdBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"key": "ar-key",
"name": "name",
"description": "description",
"status": "Active",
"predicate": "customer.email = \"example@example.org\"",
"approvers": {
"tiers": [
{
"and": [
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver0"
}
}
]
},
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver1"
}
}
]
}
]
},
{
"and": [
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver2"
}
}
]
}
]
}
]
},
"requesters": [
{
"associateRole": {
"typeId": "associate-role",
"key": "requester"
}
}
],
"businessUnit": {
"typeId": "business-unit",
"key": "bu-key"
}
}
],
"status": "Pending",
"approvals": [
{
"approver": {
"customer": {
"typeId": "customer",
"id": "9c95aece-ccfa-4cc2-98c5-6b7a5e474361"
},
"associateRoleAssignments": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver0"
},
"inheritance": "Disabled"
}
]
},
"approvedAt": "2023-04-06T17:41:28.123Z"
}
],
"eligibleApprovers": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver0"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "approver1"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "approver2"
}
}
],
"pendingApprovers": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver1"
}
},
{
"associateRole": {
"typeId": "associate-role",
"key": "approver2"
}
}
],
"currentTierPendingApprovers": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver1"
}
}
]
}
]
}
Update ApprovalFlow
Update ApprovalFlow in BusinessUnit by ID
manage_approval_flows:{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 ApprovalFlow. |
expand | The parameter can be passed multiple times. |
application/json
version ​Int​ | Expected version of the Approval Flow 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 ApprovalFlowUpdateAction​ | Update actions to be performed on the Approval Flow. |
application/json
curl https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-flows/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "reject",
"reason" : "Out of policy"
} ]
}
DATA
{
"id": "0bd46ab0-ab12-4191-be2a-749e4f0453ef",
"version": 3,
"createdAt": "2023-06-12T14:43:46.096Z",
"lastModifiedAt": "2023-06-12T14:43:46.242Z",
"lastModifiedBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"createdBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"order": {
"typeId": "order",
"id": "f6c6cd95-0a09-4dd6-9253-1cd27c70b184"
},
"businessUnit": {
"typeId": "business-unit",
"key": "bu-key"
},
"rules": [
{
"id": "ff806a85-1457-4cef-929a-79aefe85f02d",
"version": 1,
"createdAt": "2023-06-12T14:43:45.732Z",
"lastModifiedAt": "2023-06-12T14:43:45.732Z",
"lastModifiedBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"createdBy": {
"clientId": "EH-PdRPKst38wygJuKChVlBS",
"isPlatformClient": false
},
"key": "ar-key",
"name": "name",
"description": "description",
"status": "Active",
"predicate": "customer.email = \"example@example.org\"",
"approvers": {
"tiers": [
{
"and": [
{
"or": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver"
}
}
]
}
]
}
]
},
"requesters": [
{
"associateRole": {
"typeId": "associate-role",
"key": "requester"
}
}
],
"businessUnit": {
"typeId": "business-unit",
"key": "bu-key"
}
}
],
"status": "Rejected",
"rejection": {
"rejecter": {
"customer": {
"typeId": "customer",
"id": "49b7011c-f1a6-411a-a69b-724b96dab934"
},
"roles": [],
"associateRoleAssignments": [
{
"associateRole": {
"typeId": "associate-role",
"key": "approver"
},
"inheritance": "Disabled"
}
]
},
"rejectedAt": "2023-06-12T14:43:46.239Z",
"reason": "Out of policy"
},
"approvals": [],
"eligibleApprovers": [],
"pendingApprovers": [],
"currentTierPendingApprovers": []
}
Update actions
Approve
Approved
. An Associate is eligible to approve only if their roles are within tiers of the Approval Rule hierarchy that are yet to be fully approved or rejected. As such, an Associate may be able to give their approval more than once.action ​String​ | "approve" |
{
"action": "approve"
}
Reject
Rejected
.
The process takes into account all Associate Roles held by the Associate, aligning with the matched Approval Rules and their respective approver hierarchies.
Even a single rejection in the process will result in the rejection of the entire Approval Flow.An Associate is eligible to reject only if their roles are within tiers of the Approval Rule hierarchy that are yet to be rejected. An Associate may alter a prior approval into a rejection.
action ​String​ | "reject" |
reason ​String​ | The reason for the rejection of the Approval Flow. |
{
"action": "reject",
"reason": "Out of policy"
}
Set Custom Type
action ​String​ | "setCustomType" |
type ​ | Defines the Type that extends the ApprovalFlow with Custom Fields.
If absent, any existing Type and Custom Fields are removed from the ApprovalFlow. |
fields ​ | Sets the Custom Fields fields for the ApprovalFlow. |
{
"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"
}