Integrate with an external system for order approvals

The built-in Commerce approval functionality determines if an order requires approval based on a purchase limit you specify.

If you want to create more complex rules than a simple purchase limit, you can integrate with an external system that determines if an order requires approval. For example, you might want to require approval for all orders that include specific items or that are shipped to certain addresses. To integrate with an external system, you must enable approvals for an account, and configure the Order Approvals webhook.

Enable or disable order approvals

Order approval settings are defined at the account level and apply to all contacts within the account. When you integrate with an external system, the order approval feature can be enabled or disabled only in the administration interface, not on the storefront.

To enable order approval and specify that an external system should determine if orders require approval:

1. Click the Accounts icon.
2. Select the account to modify and click its Approvals tab.
3. If you are using multiple sites, select the name of the site. (Approvals are site-specific.)
4. Under Approval Settings, select Require Approval, then select Use external service to determine approval settings.
5. Click Save.

Configure the Order Approvals webhook

When a contact places an order and their account is configured to use an external service to determine whether approval is required, the server first invokes the Order Approvals function webhook. The webhook sends the following data to the external system:

• Details about the order. The request does not include certain payment details, such as credit card information. See Understand webhooks and PCI DSS compliance for information about payment details that are excluded from the request. See Order Submit request example for a sample JSON representation of an order in a webhook body.
• Shopper profile details for the contact who placed the order.
• Details about the account for which the order was placed.

To send this data to the external system, you configure the webhook by specifying the URL, username, and password for accessing the system. (See Configure webhooks for details.) You must also configure the external system to read the request data, determine whether the order requires approval, and send a response that includes the following items:

• The key approvalAction, whose value must be either true (the order requires approval) or false (the order does not require approval).
• The key approvalActionReason, whose value is a string that describes the reason approval is required if approvalAction is true. Commerce adds this string to the order’s properties and displays it in layouts and emails related to orders and approvals. See Configure page layouts for order approvals for details about layouts where this string can appear. See Notify users of order approval-related events for details about emails where this string can appear.

If approvalAction is true but approvalActionReason is missing, empty, or contains a null string, Commerce uses the string Reason unavailable.

For example, if the order requires approval because some of the products ordered are part of a specific collection, the response body might be:

{
    "approvalAction": true,
    "approvalActionReason": "Contains restricted items"
}

If Commerce cannot connect to the external system, for example in the event of an outage, or if the approvalAction key is missing, null, or contains an invalid value, the order is sent for approval. Approvers are notified, via the Order Pending For Approval email, that the order requires approval because the external system could not be reached.