Approval Rules

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.

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: 2MaxLength: 256Pattern: ^[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: 1UniqueItems
businessUnit

The Business Unit the Approval Rule belongs to.

createdAt

Date and time (UTC) the Approval Rule was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the Approval Rule was last updated.

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

ApprovalRuleDraft

key
String

User-defined unique identifier of the Approval Rule. Uniqueness is enforced within the Business Unit.

MinLength: 2MaxLength: 256Pattern: ^[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 predicate describing the Orders the Approval Rule should match against.

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: 1UniqueItems

ApprovalRulePagedQueryResponse

PagedQueryResult with results containing an array of ApprovalRule.

limit
Int
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 ApprovalRule

Approval Rules matching the query.

ApprovalRuleStatus

Indicates whether the Approval Rule should be matched against Orders or not.

Active

The Approval Rule is in effect and will be used in evaluating approval requests for Orders.

Inactive

The Approval Rule is not in effect and will not be used in evaluating approval requests for Orders.

RuleRequester

associateRole

The Associate Role that an Associate must hold for the Approval Rule to apply to the Orders they create.

RuleRequesterDraft

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

All of the nested conjunctions must be approved in order for the hierarchy to be considered approved.

MinItems: 1MaxItems: 5

ApproverConjunction

and

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

Nested conjunctions representing tiers of approvers in a hierarchy.

MinItems: 1MaxItems: 5

ApproverConjunctionDraft

and

All of the nested disjunctions must be approved in order for the conjunction to be considered approved. The total count of approvers across the nested disjunctions must not exceed 10.

MinItems: 1

ApproverDisjunctionDraft

or
Array of RuleApproverDraft

Any of the nested approvers must approve in order for the disjunction to be considered approved.

MinItems: 1

RuleApproverDraft

Any Associate with this Role can approve.

Get ApprovalRule

Get ApprovalRule in BusinessUnit by ID

GET
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules/{id}
OAuth 2.0 Scopes:
view_approval_rules:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

businessUnitKey
String

key of the BusinessUnit.

id
String

id of the ApprovalRule.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200ApprovalRuleasapplication/json
Request Example:cURL
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}'
200 Response Example: ApprovalRulejson
{
"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

GET
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules/key={key}
OAuth 2.0 Scopes:
view_approval_rules:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

businessUnitKey
String

key of the BusinessUnit.

key
String

key of the ApprovalRule.

Query parameters:
expand
The parameter can be passed multiple times.
Response:
200ApprovalRuleasapplication/json
Request Example:cURL
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}'
200 Response Example: ApprovalRulejson
{
"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

GET
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules
OAuth 2.0 Scopes:
view_approval_rules:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

businessUnitKey
String

key of the BusinessUnit.

Query parameters:
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
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:
200ApprovalRulePagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ApprovalRulePagedQueryResponsejson
{
"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

POST
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules
OAuth 2.0 Scopes:
manage_approval_rules:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

businessUnitKey
String

key of the BusinessUnit.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:ApprovalRuleDraftasapplication/json
Response:
201ApprovalRuleasapplication/json
Request Example:cURL
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
201 Response Example: ApprovalRulejson
{
"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

POST
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules/{id}
OAuth 2.0 Scopes:
manage_approval_rules:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

businessUnitKey
String

key of the BusinessUnit.

id
String

id of the ApprovalRule.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
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

Update actions to be performed on the ApprovalRule.

Response:
200ApprovalRuleasapplication/json
Request Example:cURL
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
200 Response Example: ApprovalRulejson
{
"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

POST
https://api.{region}.commercetools.com/{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/approval-rules/key={key}
OAuth 2.0 Scopes:
manage_approval_rules:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

associateId
String

id of the Customer who is acting on behalf of the BusinessUnit.

businessUnitKey
String

key of the BusinessUnit.

key
String

key of the ApprovalRule.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
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

Update actions to be performed on the ApprovalRule.

Response:
200ApprovalRuleasapplication/json
Request Example:cURL
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
200 Response Example: ApprovalRulejson
{
"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.

Example: json
{
"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.

Example: json
{
"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.

Example: json
{
"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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
Example: json
{
"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.

Example: json
{
"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.

Example: json
{
"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.

Example: json
{
"action": "setRequesters",
"requesters": [
{
"associateRole": {
"typeId": "associate-role",
"key": "buyer"
}
}
]
}