🎁 Bonus Node

The Bonus Node is a type of `calculation` node that awards a bonus based on different strategies

tiered — reward tiers based on attainment level
proportional — linear bonus proportional to attainment between thresholds
fixed — fixed amount (used when conditions are not met)

It supports target- or metric-based attainment, and optional long-term balancing (regulatory adjustments over time).

📦 JSON Representation

{
  "type": "calculation",
  "data": {
    "id": "bonus",
    "formData": {
      "type": "tiered" | "proportional" | "fixed",
      "reference_type": "target" | "metric",
      "target": {
        "id": "q1_target"
      },
      "metric": {
        "id": "customer_nps"
      },
      "tiers": [
        { "attainment": 80, "value": 1000 },
        { "attainment": 100, "value": 2000 }
      ],
      "minimum_achievement": 0.6,
      "maximum_achievement": 1.0,
      "fixed_amount": 500
    },
    "type": "calculation"
  }
}

🧾 Form Data Fields

Field	Required	Applies to	Description
`type`	✅	all	Strategy used: `tiered`, `proportional`, or `fixed`.
`reference_type`	✅	all	Whether the node measures attainment from a `target` or `metric`.
`target.id`	✅	if `reference_type = target`	ID of the target to measure performance against.
`metric.id`	✅	if `reference_type = metric`	ID of the metric to use for attainment.
`tiers`	✅	`tiered`	List of `{ attainment, value }` pairs. The first tier matched is applied.
`minimum_achievement`	✅	`proportional`	Minimum threshold to start receiving a proportional bonus.
`maximum_achievement`	✅	`proportional`	Maximum threshold to cap the proportional bonus.
`fixed_amount`	Optional	fallback	Used when no tier or proportional bonus applies.

⚙️ Execution Logic

▶️ `type = tiered`

Attainment is calculated via target or metric.
Tiers are evaluated in descending order.
The first tier where attainment ≥ threshold is applied.
Bonus value = getCompensationValue(tier.value, attainment) × outcome

▶️ `type = proportional`

Only works with reference_type = target
If attainment >= minimum_achievement:
Bonus percentage = min(attainment, maximum_achievement)
Final value = bonus percentage × target outcome
If below threshold, no bonus is paid.
Long-term regulation is optionally applied.

▶️ `type = fixed`

A fallback if no proportional/tiered bonus applies.
Bonus is always fixed_amount.

🕒 Long-Term Balancing (Regulation)

If compensationRule.long_term_balancing_period is set:

Previous payouts are fetched for the current user.
Compensation is adjusted:
compensation_value = computed_value - total_previous_payouts
Tracks:
compensation_value_before_regulation
total_previous_payouts
regulation_period

📤 Output Variables

Variable	Type	Description
`compensation_value`	`number`	Final bonus after any adjustment
`compensation_value_before_regulation`	`number`	(optional) Before subtracting past payouts
`bonus_percentage`	`number`	(proportional only) Percentage applied
`attainment`	`number`	Normalized attainment
`tier_index`	`number`	(tiered only) Matched tier index
`compensation_values`	`array`	Per-profile output for team-wide nodes
`target_outcomes`	`array`	List of `{ profile_id, outcome }` used
`total_previous_payouts`	`number` or `array`	Historical payouts for this compensation rule
`regulation_period`	`string`	Timeframe applied for long-term balancing
`context`	`object`	Contextual info (target/metric, period, attainment)

🧪 Example

Tiered bonus with 2 levels:

"tiers": [
  { "attainment": 80, "value": 1000 },
  { "attainment": 100, "value": 2000 }
]

If attainment = 0.85 (and reference is target), tier 1 is matched.
Final bonus: 1000 × outcome × 0.85

🎁 Bonus Node

On this page