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

ApprovalRuleDraft

ApprovalRulePagedQueryResponse

ApprovalRuleStatus

RuleRequester

RuleRequesterDraft

ApproverHierarchy -ApproverConjunction -ApproverDisjunction

RuleApprover

ApproverHierarchyDraft -ApproverConjunctionDraft -ApproverDisjunctionDraft -RuleApproverDraft

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` ApprovalRuleStatus	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` ApproverHierarchy	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` BusinessUnitKeyReference	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`BETA CreatedBy	IDs and references that created the ApprovalRule.
`lastModifiedAt` DateTime	Date and time (UTC) the Approval Rule was last updated.
`lastModifiedBy`BETA LastModifiedBy	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` ApprovalRuleStatus	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` ApproverHierarchyDraft	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.
`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

AssociateRoleKeyReference

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

RuleRequesterDraft

associateRole

AssociateRoleResourceIdentifier

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

AssociateRoleKeyReference

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: 1MaxItems: 5

ApproverConjunctionDraft

and

Array of ApproverDisjunctionDraft

All of the nested disjunctions must be approved in order for the conjunction to be considered approved.

MinItems: 1MaxItems: 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

AssociateRoleResourceIdentifier

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

Expansion

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

Expansion

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` QueryPredicate	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` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested.
`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. Default: `true`

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

Expansion

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

Expansion

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` Array of ApprovalRuleUpdateAction	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

Expansion

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` Array of ApprovalRuleUpdateAction	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` ApprovalRuleStatus	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` ApproverHierarchyDraft	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` TypeResourceIdentifier	Defines the Type that extends the ApprovalRule with Custom Fields. If absent, any existing Type and Custom Fields are removed from the ApprovalRule.
`fields` FieldContainer	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` CustomFieldValue	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"
}