Skip to main content

​
No-Code Commission Rules

Last Updated: December 2025
Schema Version: v0
Status: Phase 3.x Schema Definition (Validation Only)

​
Overview

No-code commission rules allow users to define commission calculation logic without writing code. Rules are stored as JSON and validated against a strict schema that enforces decimal safety (ADR-002). Current State (Phase 3.x):
  • ✅ JSON schema definition (docs/no_code_rules.schema.json)
  • ✅ Schema validation utility (api/utils/rules_schema_validate.py)
  • 🔲 Rule evaluator/engine (Phase 4)

​
Schema Structure

​
Required Fields

  • schema_version: Schema version identifier (e.g., "v0")
  • rule_id: Unique rule identifier (UUID)
  • rule_name: Human-readable rule name
  • conditions: Array of condition objects (at least one required)
  • actions: Array of action objects (at least one required)

​
Optional Fields

  • rule_description: Optional rule description
  • priority: Rule priority (0-1000, default: 0, higher = evaluated first)
  • is_active: Whether rule is active (default: true)

​
Conditions

Conditions define when a rule applies. All conditions must evaluate to true for the rule to execute.

​
Supported Operators

  • eq: Equals
  • ne: Not equals
  • gt: Greater than
  • gte: Greater than or equal
  • lt: Less than
  • lte: Less than or equal
  • in: Value is in array
  • not_in: Value is not in array
  • contains: String contains substring
  • starts_with: String starts with prefix
  • ends_with: String ends with suffix

​
Condition Examples

{
  "field": "employee_count",
  "operator": "gte",
  "value": 10
}

{
  "field": "period_code",
  "operator": "in",
  "value": ["W", "BW", "SM"]
}

{
  "field": "business_name",
  "operator": "contains",
  "value": "Dental"
}

​
Actions

Actions define what happens when conditions are met.

​
Action Types

​
1. set_rate

Set a fixed commission rate. 
{
  "type": "set_rate",
  "target_field": "commission_rate",
  "rate": "0.15"
}
Fields:
  • target_field: Field to set (e.g., "commission_rate", "pepm_rate")
  • rate: Rate as decimal string (e.g., "0.15" for 15%)
Decimal Safety: rate MUST be a string, not a number. Example: "0.15" ✅, 0.15 ❌

​
2. apply_formula

Apply a formula expression. 
{
  "type": "apply_formula",
  "target_field": "tpa_per_pay_amount",
  "formula": "{{pepm_rate}} * 12 / {{pay_periods}}"
}
Fields:
  • target_field: Field to set
  • formula: Formula expression with field references using {{field_name}} syntax
Supported Operations: +, -, *, /, parentheses () Field References: Use {{field_name}} to reference other fields (e.g., {{pepm_rate}}, {{employee_count}}) Examples:
  • "{{pepm_rate}} * 12 / {{pay_periods}}" - TPA per-pay calculation
  • "({{base_rate}} + {{bonus_rate}}) * {{employee_count}}" - Tiered calculation
  • "{{commission_rate}} * {{gross_amount}}" - Simple percentage

​
3. set_split

Set a split percentage. 
{
  "type": "set_split",
  "target_field": "split_percentage",
  "split_percentage": "33.333333"
}
Fields:
  • target_field: Field to set (typically "split_percentage")
  • split_percentage: Split percentage as decimal string
Decimal Safety: split_percentage MUST be a string, not a number. Example: "33.333333" ✅, 33.333333 ❌

​
4. apply_tier

Apply tiered rates based on a value range. 
{
  "type": "apply_tier",
  "target_field": "commission_rate",
  "tiers": [
    {
      "min": 1,
      "max": 10,
      "rate": "0.10"
    },
    {
      "min": 11,
      "max": 50,
      "rate": "0.15"
    },
    {
      "min": 51,
      "max": null,
      "rate": "0.20"
    }
  ]
}
Fields:
  • target_field: Field to set
  • tiers: Array of tier definitions
Tier Fields:
  • min: Minimum value (inclusive)
  • max: Maximum value (inclusive, null for unbounded)
  • rate: Rate as decimal string for this tier
Decimal Safety: rate MUST be a string, not a number. Example: "0.15" ✅, 0.15 ❌

​
5. set_fixed_amount

Set a fixed commission amount. 
{
  "type": "set_fixed_amount",
  "target_field": "commission_amount",
  "fixed_amount": "1000.00"
}
Fields:
  • target_field: Field to set
  • fixed_amount: Fixed amount as decimal string
Decimal Safety: fixed_amount MUST be a string, not a number. Example: "1000.00" ✅, 1000.00 ❌

​
Complete Rule Examples

​
Example 1: TPA Commission Rule

{
  "schema_version": "v0",
  "rule_id": "550e8400-e29b-41d4-a716-446655440000",
  "rule_name": "TPA Commission Rule",
  "rule_description": "Apply PEPM-based commission for TPA agents",
  "conditions": [
    {
      "field": "is_tpa_commission",
      "operator": "eq",
      "value": true
    },
    {
      "field": "pepm_rate",
      "operator": "gt",
      "value": "0"
    }
  ],
  "actions": [
    {
      "type": "apply_formula",
      "target_field": "tpa_per_pay_amount",
      "formula": "{{pepm_rate}} * 12 / {{pay_periods}}"
    },
    {
      "type": "apply_formula",
      "target_field": "agent_total",
      "formula": "{{tpa_per_pay_amount}} * {{employee_count}}"
    }
  ],
  "priority": 10,
  "is_active": true
}

​
Example 2: Tiered Commission Rate

{
  "schema_version": "v0",
  "rule_id": "660e8400-e29b-41d4-a716-446655440001",
  "rule_name": "Tiered Commission Rate",
  "rule_description": "Apply tiered commission rate based on employee count",
  "conditions": [
    {
      "field": "employee_count",
      "operator": "gte",
      "value": 1
    }
  ],
  "actions": [
    {
      "type": "apply_tier",
      "target_field": "commission_rate",
      "tiers": [
        {
          "min": 1,
          "max": 10,
          "rate": "0.10"
        },
        {
          "min": 11,
          "max": 50,
          "rate": "0.15"
        },
        {
          "min": 51,
          "max": null,
          "rate": "0.20"
        }
      ]
    }
  ],
  "priority": 5,
  "is_active": true
}

​
Example 3: Split Commission Rule

{
  "schema_version": "v0",
  "rule_id": "770e8400-e29b-41d4-a716-446655440002",
  "rule_name": "Multi-Agent Split Rule",
  "rule_description": "Split commission between multiple agents",
  "conditions": [
    {
      "field": "agent_count",
      "operator": "gt",
      "value": 1
    }
  ],
  "actions": [
    {
      "type": "set_split",
      "target_field": "split_percentage",
      "split_percentage": "33.333333"
    }
  ],
  "priority": 15,
  "is_active": true
}

​
Decimal Safety (Critical)

ADR-002: All decimal values (money, rates, percentages) MUST be strings, not numbers.

​
✅ Correct

{
  "rate": "0.15",
  "split_percentage": "33.333333",
  "fixed_amount": "1000.00"
}

​
❌ Incorrect

{
  "rate": 0.15,
  "split_percentage": 33.333333,
  "fixed_amount": 1000.00
}
Rationale: JSON numbers are IEEE 754 doubles; financial calculations require exact decimal precision.

​
Validation

Rules are validated against docs/no_code_rules.schema.json using the validation utility: 
from api.utils.rules_schema_validate import validate_rule_json

try:
    validate_rule_json(rule_dict)
    print("Rule is valid")
except ValueError as e:
    print(f"Validation error: {e}")

​
Phase 4 Roadmap

  1. Rule Evaluator: Backend engine to evaluate rules against transaction context
  2. Rule UI: No-code rule builder interface in dashboard
  3. Rule Versioning: Support for rule version history and rollback
  4. Rule Testing: Test rules against sample data before activation
  5. Rule Monitoring: Track rule execution and performance
See Also:
  • docs/no_code_rules.schema.json - JSON schema definition
  • api/utils/rules_schema_validate.py - Validation utility
  • ADR-001 and ADR-002 in Architect_Context.md - Decimal safety policy