BDS commission is a two-part flow: admins upload commission rules (Excel) per insurer, month, and department; partner/BDS systems then call an API to calculate payout for a policy using those rules.

Overview

In short:

• Setup: RuleImportController + commission_file_upload.php — import and manage rules.
• Runtime: POST getCommission → InsuranceCommissionController::initiateCommissionCalc — read JSON, pick first matching rule, return payout.
• Rules file path: writable/uploads/commission/rules/{MONYYYY}/{insurer_id}_{department}.json (e.g. SEP2025/5_motor.json).

Key files

Routes

Admin (commission group):

Runtime API:

POST getCommission
  → InsuranceCommissionController::initiateCommissionCalc
  → filter: CommissionApiFilter

How to build the commission file

Use the template from the upload screen (Download sample file) or copy from public/sample_excel/sample_commission.csv. Dev copies also live under writable/uploads/commission/files/ (e.g. sample_commission.csv, Sample_commission_file-New.xlsx). After a successful import, see the generated JSON under writable/uploads/commission/rules/{MONYYYY}/ (example: NOV2025/1_motor.json).

Required columns (row 1 headers)

Header text must match exactly (one row per rule, starting row 2). Empty cells are allowed and simply skip that condition.

Commission types (what to fill)

Sample rows (from project files)

Template header + rows (public/sample_excel/sample_commission.csv):

S.No,Premium Type,Vehicle Type,...,Commission Type,Commission Value,Commission Params (TP),Commission Params (OD),Commission Params (PA)
1,OD,Car,...,percentage,15,,,
2,TP,Two Wheeler,...,composite,,18,10,
3,COM,PCV,...,percentage,25,,,
4,COM,GCV,...,composite,,,10,

Example A — composite two-wheeler (from writable/.../rules/NOV2025/1_motor.json):

• Vehicle Type = Two Wheeler, CC Min/Max = 100
• Commission Type = composite, TP = 10, OD = 25
• Result: 10% on TP premium + 25% on OD premium when policy matches

Example B — percentage four-wheeler:

• Vehicle Type = Four Wheeler, CC = 1000, Vehicle Age Min/Max = 5
• Commission Type = percentage, Commission Value = 10
• Result: 10% of total premium

Example C — composite TP-only:

• Premium Type = TP, Vehicle Type = Four Wheeler
• Commission Type = composite, Commission Params (TP) = 10
• Result: 10% on TP premium only

Example D — flat amount:

• Vehicle Type = Two Wheeler,Four Wheeler (comma → matches either)
• Commission Type = flat, Commission Value = 500
• Result: fixed ₹500 when matched

Tips:

• Min must not be greater than Max (CC, age, weight) or the row fails validation.
• On failure, download the annotated file — errors are written into the sheet.
• Supported formats: .csv, .xlsx, .xls, .ods.
• Upload UI departments: motor, health; import logic is built for motor columns today.

Rule upload

From commission_file_upload.php the user picks insurer, commission month, department (motor / health), and an Excel/CSV file.

1. checkSameEntry — if a successful upload already exists for the same trio, SweetAlert offers Overwrite or Append (overwrite=1 or 0 on POST).
2. upload — stores file under writable/uploads/commission/files/, inserts commission_files row (pending).
3. ruleImportService->processUpload() — validates Excel rows; on success returns rules array; on failure returns annotated_file for download.
4. On success — writes JSON to rules/{MONYYYY}/{insurer_id}_{department}.json; sets file_status=success and rules_count.
5. On failure — file_status=failed; user downloads annotated_{filename} via downloadErrorFile.

Rules editor

For successful uploads, action View Rules opens commission/rules/list/{file_id} (commission_rules_list.php).

• Lists rules from the JSON file for that upload’s insurer, month, and department.
• saveRule — create or update a rule (conditions + calculation + name) in the JSON via updateCommissionRules().
• removeRule — soft-delete one rule (is_deleted=true).
• checkRuleUsage — warns if partner_policy.commission_applied_rule references the rule.
• Deleting the whole upload marks all rules with that file_id as deleted in JSON, then sets commission_files.is_active=0.

Rule JSON shape

Each rule is roughly:

{
  "id": "rule_…",
  "name": "Rule name",
  "department": "motor",
  "file_id": 12,
  "is_deleted": false,
  "conditions": [
    { "field": "vehicle_type", "operator": "==", "value": "car" }
  ],
  "calculation": {
    "type": "percentage",
    "value": 10,
    "on": "premium"
  }
}

Calculation types in InsuranceCommissionController: percentage, composite, fixed. Conditions support ==, !=, >, >=, <, <=, between, in.

Commission calculation API

initiateCommissionCalc() expects POST/JSON including at least:

• policy_issue_date — used to pick folder {MON}{YEAR} (e.g. SEP2025)
• insurer_id
• department — motor, health, etc.
• Fields referenced in rule conditions and calculation bases (e.g. premium, od_premium)

Rules with is_deleted: false are loaded; the first matching rule wins (no priority field yet).

Developer steps

1. Open /commission/list (logged-in admin).
2. Download sample file, fill rules for insurer + month + department, upload.
3. If validation fails, download the annotated error file and fix the sheet.
4. Use View Rules to tweak conditions or calculation without re-uploading the whole file.
5. Test payout: POST getCommission with the same insurer, department, and a policy_issue_date in that commission month.

Common pitfalls

• Month folder must match policy date — upload uses commission month; API uses policy_issue_date to resolve the same MONYYYY folder.
• Append vs overwrite — append merges JSON arrays; overwrite backs up the old file then replaces.
• Departments — upload UI currently offers motor and health; API department string must match the JSON filename slug.
• HTTP 200 on upload errors — check status and code in the JSON body, not only HTTP status.