A business rule pairs a condition with the actions to take when that condition is met. You supply the data to evaluate, and Chargebee returns the actions that the condition triggered. Rules let you encode quoting decisions — automatic discounts, pricing guardrails, item restrictions — once, and evaluate them consistently from anywhere in your application.
This guide takes you from nothing to a rule Chargebee is evaluating in three calls: create it, activate it, then apply it. The rule you build rewards longer commitments: a 12% invoice-level discount on quotes with a contract of at least 24 months and payment terms of 30 days or fewer.
Every call in this guide uses a full-access API key. Call these endpoints only from your backend, and never expose the key in client-side code.
Prerequisites
- Business rules enabled for your site. Contact Chargebee Support to turn them on. Until then, these endpoints return an error.
- A full-access API key for your test site.
- Your site subdomain, which appears as
{site}in the following requests.
1. Create the rule
Two parameters carry the substance of a rule. The condition goes in structured_expression, and the actions to take when it matches go in actions_on_success. Both are JSON, passed as string values in a form-encoded request.
The following expression is a GROUP node that joins two conditions with AND, so the rule matches only when both conditions are true. The action references the action-apply-discount template and supplies that template's parameters in input.
Call Create a business rule:
curl https://{site}.chargebee.com/api/v2/business_rules \
-u {fullaccess_api_key}: \
-d id="multi-year-discount" \
-d name="Apply 12 percent discount for multi-year commitments" \
-d structured_expression='{"type":"GROUP","operation":"AND","children":[{"type":"CONDITION","field":"quote.contract_duration","operator":"GREATER_THAN_OR_EQUALS","value":24},{"type":"CONDITION","field":"quote.payment_terms","operator":"LESS_THAN_OR_EQUALS","value":30}]}' \
-d actions_on_success='[{"action_template_id":"action-apply-discount","input":{"apply_on":"INVOICE_AMOUNT","discount":12.0,"discount_type":"PERCENTAGE","duration_type":"ONE_TIME"}}]'
Chargebee validates and compiles the expression when you create the rule, so a malformed expression fails here rather than at evaluation time.
The response includes latest_version set to 1 and active set to false. It also returns the stored expression, adds a type to each action based on the template that the action references, and sets released_at, because creating a rule releases its first version:
Full response
{
"business_rule": {
"id": "multi-year-discount",
"name": "Apply 12 percent discount for multi-year commitments",
"latest_version": 1,
"active": false,
"released_at": 1788510782,
"released_by": "full_access_key_v1",
"updated_at": 1788510782,
"updated_by": "full_access_key_v1",
"created_by": "full_access_key_v1",
"created_at": 1788510782,
"structured_expression": {
"type": "GROUP",
"operation": "AND",
"children": [
{
"type": "CONDITION",
"field": "quote.contract_duration",
"operator": "GREATER_THAN_OR_EQUALS",
"value": 24
},
{
"type": "CONDITION",
"field": "quote.payment_terms",
"operator": "LESS_THAN_OR_EQUALS",
"value": 30
}
]
},
"actions_on_success": [
{
"input": {
"apply_on": "INVOICE_AMOUNT",
"duration_type": "ONE_TIME",
"discount": 12.0,
"discount_type": "PERCENTAGE"
},
"action_template_id": "action-apply-discount",
"type": "APPLY_DISCOUNT"
}
],
"resource_version": 1788510782918,
"object": "business_rule"
}
}
The rule exists and its first version is released, but Chargebee doesn't evaluate it yet.
2. Activate the rule
active is an independent switch that controls whether Chargebee evaluates the rule at all. New rules are inactive, so you must activate the rule before it takes effect.
Call Activate a business rule:
curl -X POST https://{site}.chargebee.com/api/v2/business_rules/multi-year-discount/activate \
-u {fullaccess_api_key}:
The response returns the rule with active set to true. The rule is now in service.
3. Apply the rule
Applying a rule evaluates it against a context, the data that you supply for Chargebee to read. Chargebee resolves the field of each condition against this object, so quote.contract_duration reads the contract_duration key of the quote object.
Each context must include a type, which determines the schema that Chargebee uses to read the rest of the object. CPQ is the only available type.
Call Apply business rules with the rule and a context to test it against:
curl https://{site}.chargebee.com/api/v2/business_rules/apply_rules \
-u {fullaccess_api_key}: \
-d rule_id="multi-year-discount" \
-d context='{"type":"CPQ","quote":{"contract_duration":36,"payment_terms":30}}'
The response returns the context that you passed and includes one entry in rules[] for each rule that Chargebee evaluated. evaluation_result is true, and the discount to apply appears in actions:
{
"apply_rule": {
"context": {
"type": "CPQ",
"quote": { "contract_duration": 36, "payment_terms": 30 }
},
"rules": [
{
"id": "multi-year-discount",
"version": 1,
"name": "Apply 12 percent discount for multi-year commitments",
"evaluation_result": true,
"actions": [
{
"input": {
"apply_on": "INVOICE_AMOUNT",
"duration_type": "ONE_TIME",
"discount": 12.0,
"discount_type": "PERCENTAGE"
},
"action_template_id": "action-apply-discount",
"type": "APPLY_DISCOUNT"
}
],
"object": "applied_rule"
}
],
"object": "apply_rule"
}
}
Chargebee evaluates the condition and returns the action to take. Your application applies the discount to the quote.
4. Confirm the condition
A rule that matches everything looks the same as a rule that works. To confirm that the condition behaves as you intended, run the same call with a 12-month contract, which is below the threshold:
curl https://{site}.chargebee.com/api/v2/business_rules/apply_rules \
-u {fullaccess_api_key}: \
-d rule_id="multi-year-discount" \
-d context='{"type":"CPQ","quote":{"contract_duration":12,"payment_terms":30}}'
evaluation_result is now false, and the entry doesn't include actions:
{
"apply_rule": {
"context": {
"type": "CPQ",
"quote": { "contract_duration": 12, "payment_terms": 30 }
},
"rules": [
{
"id": "multi-year-discount",
"version": 1,
"name": "Apply 12 percent discount for multi-year commitments",
"evaluation_result": false,
"object": "applied_rule"
}
],
"object": "apply_rule"
}
}
A condition that references a field that the context doesn't include also evaluates to false, and Chargebee doesn't return an error. If a rule that you expect to match returns false, check that the context includes every field that the conditions reference, spelled exactly as the schema spells it.
Test an expression before you store it
While you're still working out a condition, you don't need to create a rule to try it. Pass structured_expression directly to Apply business rules with evaluate set to true. The following expression uses ANY_OF, which takes values rather than a single value:
curl https://{site}.chargebee.com/api/v2/business_rules/apply_rules \
-u {fullaccess_api_key}: \
-d evaluate=true \
-d structured_expression='{"type":"CONDITION","field":"quote.billing_address_country","operator":"ANY_OF","values":["US","CA"]}' \
-d context='{"type":"CPQ","quote":{"billing_address_country":"US"}}'
The rules[] entry that Chargebee returns for an ad hoc expression includes only evaluation_result, because there's no stored rule to describe and no actions to run.
Next steps
- Business Rules API reference for the full parameter list, the node types and operators available in an expression, the fields a context can carry, and the action templates you can reference.
- Business Rulesets to group related rules and evaluate them together in priority order.
We're always happy to help you with any questions you might have! Click here to reach out to us.
In this Page