Approval Rules

Elevate, May 20-22-2025, Miami Beach, Florida

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​

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

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

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:
200

ApprovalRule

asapplication/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:
200

ApprovalRule

asapplication/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
​

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 false to improve query performance when the total is not needed.

Default: ​
Response:
200

ApprovalRulePagedQueryResponse

asapplication/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:
201

ApprovalRule

asapplication/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:ApprovalRuleUpdateasapplication/json
Response:
200

ApprovalRule

asapplication/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:ApprovalRuleUpdateasapplication/json
Response:
200

ApprovalRule

asapplication/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: 2​MaxLength: 256​Pattern: ^[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"
      }
    }
  ]
}

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.

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

Example: json
{
  "action": "setCustomField",
  "name": "exampleStringField",
  "value": "TextString"
}