Documentation
All Release Notes

Introduced Buyer Approval Flows in beta

19 September 2023
Composable Commerce
HTTP API
New feature
B2BOrdersMessages/SubscriptionsGraphQL

We have released Buyer Approval Flows in public beta. This new feature provides a flexible Order approval process for Business Units. Orders can now be matched to Approval Rules, which determine whether an Order must go through an approval process, and if so, which Associate Roles are needed to approve it. During the approval process, an Approval Flow manages the overall approval state.

With the help of Buyer Approval Flows, you can control each step of the Order approval process, based on the requirements of your organization.

This feature is only available as part of Composable Commerce for B2B and will be subject to additional terms and pricing. To get access to Composable Commerce for B2B, contact the Composable Commerce support team.

Changes:

  • [API] Added Approval Rules and Approval Flows APIs.
  • [API] Added ApprovalFlowApprovedMessage, ApprovalFlowCompletedMessage, ApprovalFlowCreatedMessage, ApprovalFlowRejectedMessage Messages.
  • [API] Added ApprovalRuleApproversSetMessage, ApprovalRuleCreatedMessage, ApprovalRuleDescriptionSetMessage, ApprovalRuleKeySetMessage, ApprovalRuleNameSetMessage, ApprovalRulePredicateSetMessage, ApprovalRuleRequestersSetMessage, ApprovalRuleStatusSetMessage Messages.
  • [API] Added CreateApprovalRules, UpdateApprovalRules, and UpdateApprovalFlows Permissions.
  • [GraphQL API] Changed the Permission type:
    • Enum values CreateApprovalRules, UpdateApprovalRules and UpdateApprovalFlows were added to enum Permission.
  • [GraphQL API] Changed the AsAssociate type:
    • Added the approvalFlow, approvalFlows, approvalRule and approvalRules fields to the AsAssociate type.
  • [GraphQL API] Changed the Mutation type:
    • Added the createApprovalRule, updateApprovalRule, and updateApprovalFlow fields to the Mutation type.
  • [GraphQL API] Added the following types to the GraphQL schema: ApprovalFlow, ApprovalFlowApproval, ApprovalFlowApproved, ApprovalFlowCompleted, ApprovalFlowCreated, ApprovalFlowQueryResult, ApprovalFlowRejected, ApprovalFlowRejection, ApprovalFlowUpdateAction, ApprovalRule, ApprovalRuleApproversSet, ApprovalRuleCreated, ApprovalRuleDescriptionSet, ApprovalRuleDraft, ApprovalRuleKeySet, ApprovalRuleNameSet, ApprovalRulePredicateSet, ApprovalRuleQueryResult, ApprovalRuleRequestersSet, ApprovalRuleStatus, ApprovalRuleStatusSet, ApprovalRuleUpdateAction, ApproveApprovalFlow, ApproverConjunction, ApproverConjunctionDraft, ApproverDisjunction, ApproverDisjunctionDraft, ApproverHierarchy, ApproverHierarchyDraft, RejectApprovalFlow, RuleApprover, RuleApproverDraft, RuleRequester, RuleRequesterDraft, SetApprovalRuleApprovers, SetApprovalRuleDescription, SetApprovalRuleKey, SetApprovalRuleName, SetApprovalRulePredicate, SetApprovalRuleRequesters, SetApprovalRuleStatus.

The following changes were introduced in terms of GraphQL SDL:

extend type AsAssociate {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  approvalFlow(id: String!): ApprovalFlow


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  approvalFlows(where: String, sort: [String!], limit: Int, offset: Int): ApprovalFlowQueryResult!


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  approvalRule(
    "Queries with specified ID"
    id: String,


    "Queries with specified key"
    key: String): ApprovalRule


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  approvalRules(where: String, sort: [String!], limit: Int, offset: Int): ApprovalRuleQueryResult!
}


extend type Mutation {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  createApprovalRule(draft: ApprovalRuleDraft!,


    "Create/modify entity as an associate in business-unit."
    asAssociate: AsAssociateArgument!): ApprovalRule


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  updateApprovalFlow(version: Long!, actions: [ApprovalFlowUpdateAction!]!,


    "Create/modify entity as an associate in business-unit."
    asAssociate: AsAssociateArgument!, id: String!): ApprovalFlow


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  updateApprovalRule(version: Long!, actions: [ApprovalRuleUpdateAction!]!,


    "Create/modify entity as an associate in business-unit."
    asAssociate: AsAssociateArgument!,


    "Queries with specified ID"
    id: String,


    "Queries with specified key"
    key: String): ApprovalRule
}


extend enum Permission {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  CreateApprovalRules


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  UpdateApprovalFlows


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  UpdateApprovalRules
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalFlow implements Versioned {
  status: String!
  approvals: [ApprovalFlowApproval!]!
  rejection: ApprovalFlowRejection
  orderRef: Reference!
  order: Order
  rules: [ApprovalRule!]!
  businessUnitRef: KeyReference!
  businessUnit: BusinessUnit!
  eligibleApprovers: [RuleApprover!]!
  pendingApprovers: [RuleApprover!]!
  currentTierPendingApprovers: [RuleApprover!]!
  id: String!
  version: Long!
  createdAt: DateTime!
  lastModifiedAt: DateTime!
  createdBy: Initiator
  lastModifiedBy: Initiator
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalFlowApproval {
  approver: Associate!
  approvedAt: DateTime!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalFlowApproved implements MessagePayload {
  associate: Customer
  order: Order
  associateRef: Reference
  orderRef: Reference
  type: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalFlowCompleted implements MessagePayload {
  status: String!
  order: Order
  orderRef: Reference
  type: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalFlowCreated implements MessagePayload {
  approvalFlow: ApprovalFlow!
  type: String!
}


type ApprovalFlowQueryResult {
  offset: Int!
  count: Int!
  total: Long!


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  exists: Boolean!
  results: [ApprovalFlow!]!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalFlowRejected implements MessagePayload {
  rejectionReason: String
  associate: Customer
  order: Order
  associateRef: Reference
  orderRef: Reference
  type: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalFlowRejection {
  rejecter: Associate!
  rejectedAt: DateTime!
  reason: String
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ApprovalFlowUpdateAction {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  approve: ApproveApprovalFlow


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  reject: RejectApprovalFlow
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalRule implements Versioned {
  key: String
  name: String!
  description: String
  status: ApprovalRuleStatus!
  predicate: String!
  approvers: ApproverHierarchy!
  requesters: [RuleRequester!]!
  businessUnitRef: KeyReference!
  businessUnit: BusinessUnit!
  id: String!
  version: Long!
  createdAt: DateTime!
  lastModifiedAt: DateTime!
  createdBy: Initiator
  lastModifiedBy: Initiator
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalRuleApproversSet implements MessagePayload {
  oldApprovers: ApproverHierarchy!
  approvers: ApproverHierarchy!
  type: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalRuleCreated implements MessagePayload {
  approvalRule: ApprovalRule!
  type: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalRuleDescriptionSet implements MessagePayload {
  oldDescription: String
  description: String
  type: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ApprovalRuleDraft {
  key: String
  name: String!
  description: String
  status: ApprovalRuleStatus!
  predicate: String!
  approvers: ApproverHierarchyDraft!
  requesters: [RuleRequesterDraft!]!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalRuleKeySet implements MessagePayload {
  oldKey: String
  key: String
  type: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalRuleNameSet implements MessagePayload {
  oldName: String!
  name: String!
  type: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalRulePredicateSet implements MessagePayload {
  oldPredicate: String!
  predicate: String!
  type: String!
}


type ApprovalRuleQueryResult {
  offset: Int!
  count: Int!
  total: Long!


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  exists: Boolean!
  results: [ApprovalRule!]!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalRuleRequestersSet implements MessagePayload {
  oldRequesters: [RuleRequester!]!
  requesters: [RuleRequester!]!
  type: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
enum ApprovalRuleStatus {
  Active
  Inactive
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApprovalRuleStatusSet implements MessagePayload {
  oldStatus: ApprovalRuleStatus!
  status: ApprovalRuleStatus!
  type: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ApprovalRuleUpdateAction {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setApprovers: SetApprovalRuleApprovers


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setKey: SetApprovalRuleKey


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setName: SetApprovalRuleName


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setDescription: SetApprovalRuleDescription


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setPredicate: SetApprovalRulePredicate


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setRequesters: SetApprovalRuleRequesters


  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  setStatus: SetApprovalRuleStatus
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ApproveApprovalFlow {
  dummy: String
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApproverConjunction {
  and: [ApproverDisjunction!]!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ApproverConjunctionDraft {
  and: [ApproverDisjunctionDraft!]!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApproverDisjunction {
  or: [RuleApprover!]!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ApproverDisjunctionDraft {
  or: [RuleApproverDraft!]!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ApproverHierarchy {
  tiers: [ApproverConjunction!]!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ApproverHierarchyDraft {
  tiers: [ApproverConjunctionDraft!]!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input RejectApprovalFlow {
  reason: String
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type RuleApprover {
  associateRole: AssociateRole!
  associateRoleRef: KeyReference!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input RuleApproverDraft {
  associateRole: ResourceIdentifierInput!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type RuleRequester {
  associateRole: AssociateRole!
  associateRoleRef: KeyReference!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input RuleRequesterDraft {
  associateRole: ResourceIdentifierInput!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetApprovalRuleApprovers {
  approvers: ApproverHierarchyDraft!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetApprovalRuleDescription {
  description: String
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetApprovalRuleKey {
  key: String
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetApprovalRuleName {
  name: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetApprovalRulePredicate {
  predicate: String!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetApprovalRuleRequesters {
  requesters: [RuleRequesterDraft!]!
}


"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SetApprovalRuleStatus {
  status: ApprovalRuleStatus!
}