Sales Commissions (عمولات المبيعات)

Sales commissions allow you to automatically calculate and track commissions for salespeople when invoices are posted. The system supports flexible rule-based calculation with priority ordering.

Commission Rules

Rules define how commissions are calculated. Each rule can target a specific salesperson, product category, or product, with priority-based matching.

Rule Attributes

Field	Type	Description
id	integer	Auto-generated
salesperson_id	integer?	Target specific salesperson (null = all)
product_category_id	integer?	Target specific category (null = all)
product_id	integer?	Target specific product (null = all)
commission_type	enum	percentage, fixed_per_unit, fixed_per_invoice
rate	decimal(15,3)	Commission rate
min_invoice_amount	decimal(15,3)?	Minimum invoice total to qualify
is_active	boolean	Whether this rule is active
priority	integer	Higher priority = matched first

Commission Types

Type	Calculation
percentage	line_total × rate / 100
fixed_per_unit	quantity × rate
fixed_per_invoice	rate / line_count (distributed across items)

Commission Records

When a sales invoice is posted and commission is enabled, the system creates a commission record.

Commission Attributes

Field	Type	Description
id	integer	Auto-generated
salesperson_id	integer	The salesperson
invoice_id	integer	Source invoice
invoice_number	string	Invoice number
invoice_date	date	Invoice date
partner_id	integer?	Customer
invoice_total	decimal(15,3)	Invoice total amount
commission_base	decimal(15,3)	Base amount for commission
commission_rate	decimal(8,4)	Effective commission rate
commission_amount	decimal(15,3)	Calculated commission amount
status	enum	pending, approved, paid, cancelled
paid_date	date?	When commission was paid
paid_via	string?	Payment method
notes	text?	Optional notes

Commission Workflow

Rule Matching Logic

When calculating commission for an invoice line item, the service finds the best matching rule:

1. Priority-based: Higher priority rules are checked first
2. Specificity fallback: Product-specific > Category-specific > Salesperson-specific > Company default
3. Settings fallback: If no rule matches, uses sales.default_commission_rate setting

API Endpoints

Commission Rules

Method	Endpoint	Description
GET	/api/sales/commission-rules	List rules (ordered by priority)
POST	/api/sales/commission-rules	Create rule
PUT	/api/sales/commission-rules/{id}	Update rule
DELETE	/api/sales/commission-rules/{id}	Soft-delete rule

Commissions

Method	Endpoint	Description
GET	/api/sales/commissions	List commissions
GET	/api/sales/commissions/summary	Summary by salesperson
POST	/api/sales/commissions/{id}/approve	Approve commission
POST	/api/sales/commissions/{id}/mark-paid	Mark as paid
POST	/api/sales/commissions/bulk-approve	Bulk approve
POST	/api/sales/commissions/bulk-mark-paid	Bulk mark paid

Query Parameters (List Commissions)

Parameter	Type	Description
salesperson_id	integer	Filter by salesperson
partner_id	integer	Filter by customer
status	string	Filter by status
date_from	date	Filter from date
date_to	date	Filter to date

Examples

Create a Commission Rule

curl

curl -X POST "$BASE_URL/api/sales/commission-rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "commission_type": "percentage",
    "rate": 5.000,
    "priority": 10,
    "is_active": true
  }'

Dart

final response = await dio.post(
  '/api/sales/commission-rules',
  data: {
    'commission_type': 'percentage',
    'rate': 5.000,
    'priority': 10,
    'is_active': true,
  },
);

Approve a Commission

curl

curl -X POST "$BASE_URL/api/sales/commissions/1/approve" \
  -H "Authorization: Bearer $TOKEN"

Dart

final response = await dio.post('/api/sales/commissions/1/approve');

Bulk Mark as Paid

curl

curl -X POST "$BASE_URL/api/sales/commissions/bulk-mark-paid" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [1, 2, 3],
    "paid_date": "2026-03-01",
    "paid_via": "bank_transfer"
  }'

Dart

final response = await dio.post(
  '/api/sales/commissions/bulk-mark-paid',
  data: {
    'ids': [1, 2, 3],
    'paid_date': '2026-03-01',
    'paid_via': 'bank_transfer',
  },
);

Settings

Commission behavior is controlled by two settings:

Setting Key	Type	Description
sales.commission_enabled	boolean	Enable/disable commission calculation
sales.default_commission_rate	decimal	Fallback rate when no rule matches

Permissions

Permission	Description
sales.commissions.view	View commissions and rules
sales.commissions.manage	Create/update/delete rules, approve/pay commissions