Apply business rules

Idempotency Supported

Evaluates business rules against a context that you supply. You can evaluate a single rule using rule_id, every rule in a ruleset using ruleset_id, or an ad hoc expression using structured_expression. Set evaluate to true to return only the evaluation result without running the actions configured on the rules.

These three parameters are independent of one another rather than alternatives. Passing more than one evaluates each of them in the same request and returns the results together, so a request carrying both rule_id and ruleset_id evaluates that rule and that ruleset.

The response returns one entry in apply_rule.rules[] for each rule that was evaluated, carrying the evaluation_result of its expression, the actions that the result triggered, and an error_message when the rule could not be evaluated. The entry for an ad hoc structured_expression carries only evaluation_result, because there is no stored rule to describe.

Prerequisites & Constraints

Business rules must be enabled for the site.
A rule referenced by rule_id must be released and active, and a ruleset referenced by ruleset_id must be active.

Use Cases

Evaluate a single rule

Pass rule_id along with the context. The latest released version of that rule is evaluated on its own.

Evaluate a group of rules together

Pass ruleset_id along with the context. The rules in the ruleset are evaluated in their priority order, and the ruleset execute_mode decides whether evaluation stops early and which results are returned.

Test an expression before saving it

Pass structured_expression and the context you want to test it against, with evaluate set to true. This evaluates the expression without creating a rule and without executing any actions.

Sample Request

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/business_rules/apply_rules

Input Parameters

evaluate

optional, boolean

When set to true, skips rule action execution and only performs rule evaluation. Useful for testing rule conditions without executing associated actions.

rule_id

optional, string

The business rule to evaluate. Its latest released version is evaluated, and one entry is returned for it in apply_rule.rules[].

ruleset_id

optional, string

The business ruleset to evaluate. Every rule it contains is evaluated in its priority order, following the strategy configured in the ruleset execute_mode, which also decides whether evaluation stops early and which of the results are returned.

skip_failed_rules

optional, boolean

Skip failed rules and continue processing the rest of the ruleset. A rule that could not be evaluated is returned with error_message set. When false, the request fails as soon as a rule cannot be evaluated.

This applies only to the rules evaluated through ruleset_id. A rule evaluated through rule_id and an expression evaluated through structured_expression fail the request regardless of this value.

structured_expression

optional, jsonobject

An expression to evaluate without storing it as a rule. Use it to try an expression while you are building it. See Expressions for the node types and the operators each field type supports.

Impacts

The entry returned for the expression in apply_rule.rules[] carries only evaluation_result. No actions run, because actions belong to a stored rule rather than to an ad-hoc expression.
An operator applied to a field of another type cannot be evaluated and fails the request. skip_failed_rules does not apply to this parameter.

Example → structured_expression = {"type":"GROUP","operation":"AND","children":[{"type":"CONDITION","field":"customer.language","operator":"CONTAINS","value":"en"},{"type":"CONDITION","field":"quote.shipping_address_country","operator":"ANY_OF","values":["IN","US"]}]}

context

optional, jsonobject

The data that the rule expressions are evaluated against, passed as a JSON object. The field of each condition is resolved against this object. See Context for the schema and the fields a condition can reference.

Constraints

Must carry a type, which selects the schema that the rest of the object is read as. CPQ is the only type available.

Impacts

A key that falls outside the schema is dropped as the context is read.
A condition that references a field the context does not carry, including a key dropped for falling outside the schema, evaluates to false. The rule holding it does not match, and no error_message is returned for it.

Example → context = {"type":"CPQ","customer":{"language":"en"},"quote":{"shipping_address_country":"IN"}}

Returns

apply_rule

Apply rule object

The outcome of the evaluation. It echoes back the context you passed and carries one entry in rules[] for each rule that was evaluated.

Each entry in rules[] holds the following.

id and version: the rule that was evaluated, and the released version that was used.
name and description: carried over from the rule.
evaluation_result: true when the rule expression matched the context, and false when it did not.
actions: the actions produced when evaluation_result is true, each carrying its type, the action_template_id of the template it was built from, and that template's parameters in input. It is absent for a rule that did not match. See Actions for what each template returns.
error_message: the reason a rule could not be evaluated, such as an operator used on a field of another type. It is returned when skip_failed_rules is true.

When you pass ruleset_id, which of the evaluated rules appear in rules[] depends on the execute_mode of the ruleset. See Evaluation results for an annotated response, and Context for the fields the echoed context can carry.