💰 Commission Node

The Commission Node is a `calculation` node that computes commissions based on configurable strategies

Straight commission: fixed percentage over a value.
Field-based commission: dynamic percentage from a record field.
Tiered commission: attainment-based tier lookup.
Piecework: fixed payout per qualifying record.

Commissions can be calculated either:

Per-record (default), or
Over a metric period if outcome_period is set in the compensation rule.

📦 JSON Representation

{
  "type": "calculation",
  "data": {
    "id": "commission",
    "formData": {
      "type": "tiered" | "straight" | "field" | "piecework",
      "reference_type": "target" | "metric" | "column",
      "percentage": 0.1,
      "fixed_amount": 100,
      "percentage_column": { "name": "deal.$commission_pct" },
      "calculate_over_column": { "name": "deal.$amount" },
      "calculate_over_metric": { "id": "mrr_generated" },
      "tiers": [
        { "attainment": 80, "value": 0.05 },
        { "attainment": 100, "value": 0.1 }
      ],
      "targets": [{ "id": "q1_target" }],
      "column": { "name": "deal.$attainment_score" },
      "cap_target_achievement": true,
      "metric": { "id": "mrr_generated" },
      "metric_period": "month" | "quarter" | "half_year" | "year"
    },
    "type": "calculation"
  }
}

🧾 Form Data Fields

Field	Required	Applies to	Description
`type`	✅	all	Type of commission: `straight`, `field`, `tiered`, or `piecework`.
`percentage`	✅	`straight`	Flat commission percentage (e.g. 0.1 = 10%).
`percentage_column.name`	✅	`field`	Field used to fetch dynamic percentage (e.g., `deal.$commission_pct`).
`calculate_over_column.name`	✅	most	Field from which to take the base value (e.g., `deal.$amount`).
`calculate_over_metric.id`	✅	if `outcome_period` and type is `straight`	Metric to compute base value over time.
`fixed_amount`	✅	`piecework`	Static amount to pay per record.
`reference_type`	✅	`tiered`	How attainment is measured: `target`, `metric`, or `column`.
`targets[].id`	✅	if `reference_type = target`	List of target IDs.
`column.name`	✅	if `reference_type = column`	Field holding the attainment value.
`metric.id`	✅	if `reference_type = metric`	Metric used to compute attainment.
`metric_period`	✅	if `reference_type = metric`	Period to aggregate metric over.
`cap_target_achievement`	Optional	`target`	If true, caps target-based attainment at 1.0 (100%).
`tiers[].attainment`	✅	`tiered`	Required attainment threshold (e.g. 100).
`tiers[].value`	✅	`tiered`	Value or percentage to apply when tier is matched.

⚙️ Execution Logic

▶️ `type = straight`

If outcome_period is not set:
Commission = percentage × calculate_over_column.
If outcome_period is set:
Commission = percentage × metricValue for the defined period.

▶️ `type = field`

Percentage is fetched from percentage_column (e.g., 5 → 0.05).
Commission = field_percentage × calculate_over_column.

▶️ `type = tiered`

Attainment is computed from either:
Target achievements (reference_type = target)
Metric value (reference_type = metric)
Direct field (reference_type = column)
Attainment (possibly scaled to %) is compared against tier thresholds.
First matching tier is used.
Commission = tier_value × calculate_over_column or metric.

▶️ `type = piecework`

Returns fixed_amount as the commission.

📈 Attainment Calculation

`reference_type`	Source	Calculation
`target`	Targets	Avg target achievement (optionally capped at 1.0).
`metric`	Metrics	Value over the configured period.
`column`	Record field	Direct value from the field.

If reference_type = target, attainment is multiplied by 100 to match tier values like 80/100.

📤 Output Variables

Variable	Description
`commission_percentage`	Final percentage used (straight/field/tiered).
`compensation_value`	Final commission calculated.
`field_value`	Value from `calculate_over_column`.
`metric_value`	Value from metric (if used).
`attainment`	Computed attainment (if tiered).
`tier_index`	Index of matched tier (if tiered).
`context`	Object with `attainment`, `metric`, and `period` (when using metrics).

🧪 Example

Tiered commission over a record field:

"tiers": [
  { "attainment": 80, "value": 0.05 },
  { "attainment": 100, "value": 0.1 }
]

Attainment = 95
Matches second tier: 0.05
Commission = 0.05 × deal.$amount

💰 Commission Node

On this page