Business Rule

A business rule pairs a condition with the actions to take when that condition is met. You supply the context to evaluate, and Chargebee returns the actions configured in actions_on_success when the condition evaluates to true.

The condition is defined in structured_expression, a JSON representation of the rule logic that visual editors and dynamic rule builders can both read and write. Chargebee validates and compiles the expression when the rule is created or updated, and evaluates the compiled form when you call Apply business rules.

The field of every condition is resolved against the context supplied at evaluation time, so the fields you reference must match the keys of the context the rule is evaluated against. A condition whose field is absent from the context never evaluates to true, which means the rule never matches.

Business rules are versioned. Creating a rule releases its first version, so latest_version is 1 and released_at is set from the outset. Editing a rule leaves that released version untouched: the first edit creates a draft, and every later edit updates the same draft. Releasing the draft promotes it to the next version number, and that version becomes the latest released version and the one Chargebee evaluates. Until you release it, the previously released version stays in effect, so a rule can keep serving traffic while its next version is being prepared.

The active attribute is an independent switch that controls whether Chargebee evaluates the rule at all. A rule is created inactive, so it has to be activated before it takes effect.

Related rules can be grouped into a business ruleset, which evaluates its member rules in priority order using the strategy configured in the ruleset's execute_mode.

For a walkthrough that creates, activates, and applies a rule in three calls, take a look at the Business Rules quickstart.

Expressions

The structured_expression of a rule is a tree of nodes that evaluates to a single true or false. Every node carries a type, which determines the rest of the fields the node takes.

The following expression matches a quote from a customer whose language contains en and whose shipping country is India or the United States:

Every condition is compiled so that it first tests whether the field is present in the context. A condition on a field that the context doesn't carry evaluates to false instead of failing, so the rule that holds it never matches and no error_message is returned for it.

Context

The context you pass to Apply business rules isn't a free-form object. Its type selects the schema that the rest of the context is read as, and CPQ is the only type available, so a condition can reference only the fields of that schema. A key that falls outside the schema is dropped as the context is read, so a condition on it never evaluates to true. A misspelled or unsupported key therefore surfaces as an unmet condition rather than as an error.

A CPQ context carries items, quote, customer, user, site, and quote_subscription, each of them optional. Pass only the parts the rules you're evaluating need:

A condition addresses a field by its path through the context, so customer.language reads the language of the customer. A COLLECTION node on items iterates over the entries of that array.

Each custom_fields object holds your own fields keyed by name, and every value must be a string, a number, or a boolean. A condition reads one through its key, as in quote.custom_fields.region.

The response returns the context back with rule_ids filled in on the quote and on each item, so you can see which rules applied where.

Actions

Every entry in actions_on_success is built from an action template, a built-in definition that fixes the kind of change an action makes and the parameters it accepts. An action names its template in action_template_id and passes that template's parameters in input:

The type of an action is derived from its template, so it's returned with the action but you don't have to pass it. A parameter that the template doesn't define is rejected. The values of enumerated parameters are matched without regard to case, and are returned in the input of the action exactly as you passed them.

An action can also carry a structured_expression of its own, written in the same format as the expression of the rule. The rule decides whether the action runs at all, and the action's own expression then narrows it to the items of the context that satisfy that expression. One rule can therefore discount some of the items it matched rather than all of them. Only the apply discount, limit discount, and limit quantity templates accept an action-level expression.

Evaluation results

Apply business rules returns an apply_rule object that echoes back the context you passed and carries one entry in rules for each rule it evaluated:

Read the result of each rule from evaluation_result, and read what the rule produced from actions. Two things about the shape are worth knowing before you write code against it.

• actions is absent, rather than empty, for a rule whose evaluation_result is false. The second entry above shows a rule that didn't match.
• An entry for an ad hoc structured_expression carries only evaluation_result, because there's no stored rule to report an id, name, or actions for.

A rule that couldn't be evaluated is returned with error_message set instead, but only if you passed skip_failed_rules as true. Otherwise the request fails. For the full list of fields, see the response of Apply business rules.