Commission Ledger¶

The Commission Ledger is the historical record of commission calculations.

Every commission generated by the Incentive Compensation Engine is recorded as a ledger entry. The ledger preserves the transaction, configuration, calculation inputs, and resulting commission amount used at the time of calculation.

Commission Ledger entries are immutable.

This makes the ledger the audit trail for commission calculations.

Purpose¶

The Commission Ledger answers:

Which transaction generated the commission?
Who received the commission?
Which Commission Plan was used?
Which Commission Rule was used?
How was the commission calculated?
What amount was used as the calculation base?
What commission amount was produced?
When was the commission calculated?
Has the commission later been reversed?

The ledger is therefore the bridge between the original ERPNext transaction and downstream statement and payout processing.

Where the Ledger Fits¶

The ledger sits immediately after commission calculation:

ERPNext Sales Invoice
        ↓
Commission Evaluation
        ↓
Commission Ledger
        ↓
Commission Statement
        ↓
Commission Payout

A Sales Invoice is the source transaction.

The Commission Ledger records the result of evaluating that transaction.

Commission Statements then group eligible ledger entries for a payee and period.

Fields¶

Field	Description
Sales Invoice	Source ERPNext Sales Invoice
Sales Invoice Item	Source Sales Invoice item
Commission Payee	Recipient of the commission
Commission Rule	Rule used to calculate the commission
Commission Plan	Plan under which the rule was evaluated
Calculation Method	Method used for the calculation
Rate	Commission rate used when applicable
Commission Amount	Calculated commission amount
Base Amount	Amount used as the calculation base
Fixed Amount	Fixed amount used when applicable
Status	Current processing state of the ledger entry
Transaction Date	Date of the source transaction
Calculation Date	Date and time when the commission was calculated
Source Key	Unique key used to identify the source calculation
Reversal Of	Original ledger entry referenced by a reversal
Entry Type	Commission, Reversal, or Adjustment
Company	Company associated with the transaction
Currency	Currency used for the commission

Commission Entries¶

A normal commission calculation creates an entry with:

Entry Type: Commission

For example:

Sales Invoice:       ACC-SINV-2026-00021
Commission Payee:    Test Salesperson
Commission Rule:     Demo Item Commission
Commission Plan:     Standard Sales Commission
Base Amount:         ₹10,000
Rate:                5%
Commission Amount:   ₹500
Entry Type:          Commission

This entry becomes the historical record of the ₹500 commission calculation.

Calculation Snapshot¶

The ledger stores the calculation information at the time the commission is created.

For example:

Base Amount:  ₹10,000
Rate:         5%
Commission:   ₹500

If the Commission Rule is later changed to 7%, the existing ledger entry remains:

Base Amount:  ₹10,000
Rate:         5%
Commission:   ₹500

The ledger does not recalculate itself from the current rule configuration.

This is important for auditability.

Immutability¶

Commission Ledger entries are immutable after creation.

The calculation-related information cannot be changed after the entry has been created, and ledger entries cannot be deleted or renamed through normal document operations.

The application treats the ledger as a historical record rather than an editable configuration document.

The Commission Ledger form also indicates this explicitly:

This commission ledger entry is an immutable audit record. It is generated automatically from the source transaction and cannot be edited or deleted.

This prevents historical commission calculations from being silently changed after they have been used for statements or payouts.

Why Immutability Matters¶

Consider a commission that was calculated at 5%:

Sales Amount = ₹10,000
Commission   = ₹500

Later, the company changes the rule to 7%.

If the historical ledger were recalculated automatically, the old commission could become:

Commission = ₹700

That would make it impossible to reliably determine what was originally calculated.

With an immutable ledger:

Original calculation
₹10,000 × 5% = ₹500

remains permanently recorded.

The new 7% configuration applies to future calculations instead.

Source Key and Idempotency¶

Each ledger entry contains a Source Key.

The source key identifies the source transaction and calculation context used to create the entry.

The commission engine uses this key to prevent duplicate ledger entries when the same commission event is processed more than once.

Conceptually:

Source Transaction
       +
Sales Invoice Item
       +
Commission Payee
       +
Commission Rule
       +
Entry Type
       ↓
Source Key

If an entry with the same source key already exists, the engine does not create another duplicate commission entry.

This makes commission generation idempotent.

Sales Team Allocation¶

The commission engine can use the Sales Team information from the Sales Invoice when determining commission recipients and contribution.

For example:

Sales Invoice
      │
      └── Sales Team
             │
             ├── Sales Person A → 60%
             └── Sales Person B → 40%

The transaction builder can use these contribution percentages when creating the commission calculation inputs.

This allows commission to be allocated according to the sales contribution recorded on the source transaction.

Ledger Status¶

A Commission Ledger entry can have the following status:

Calculated
Under Review
Approved
Posted
Reversed
Cancelled

These statuses represent the processing state of the commission record.

A calculated commission can subsequently participate in statement processing and downstream approval and payout workflows.

Reversals¶

The original commission entry is not modified when a source Sales Invoice is cancelled.

Instead, the application creates a separate reversal ledger entry.

For example:

Original Commission

Entry Type:        Commission
Commission Amount: ₹500
Status:            Calculated

If the source invoice is cancelled, a separate entry is created:

Reversal

Entry Type:        Reversal
Commission Amount: -₹500
Reversal Of:       Original Ledger Entry

The original entry remains available as part of the historical audit trail.

The reversal records the effect of cancelling the source transaction.

Why Reversals Use Separate Entries¶

A separate reversal entry preserves both sides of the history:

Original Commission
        +
Reversal
        =
Net Effect

This is preferable to changing the original record because it allows the system to answer both:

What commission was originally calculated?
What happened to that commission later?

The ledger therefore represents a sequence of historical events rather than a single mutable balance.

Statement Processing¶

Commission Statements use the Commission Ledger as their source of eligible commission entries.

When a Draft statement is generated, the application searches for ledger entries matching the statement's:

Commission Payee
Company
Currency
date range

Eligible entries that have not already been included in another non-cancelled statement can be added to the statement.

The statement then stores the selected ledger entries as part of its immutable snapshot.

Conceptually:

Commission Ledger
      │
      ├── Ledger Entry 1
      ├── Ledger Entry 2
      ├── Ledger Entry 3
      └── Ledger Entry 4
             │
             ▼
      Commission Statement

Example¶

Suppose a salesperson has three eligible commission entries:

CL-2026-00001 → ₹500
CL-2026-00002 → ₹750
CL-2026-00003 → ₹250

The statement for the relevant period can include:

Gross Commission = ₹1,500
Adjustments      = ₹0
Net Commission   = ₹1,500

The statement references the underlying ledger entries so that the commission total can be traced back to its source calculations.

Audit Trail¶

The Commission Ledger creates a traceable chain from the original transaction to the final payout:

Sales Invoice
     ↓
Commission Rule
     ↓
Commission Ledger
     ↓
Commission Statement
     ↓
Commission Payout

This allows an administrator or reviewer to trace a paid commission back to the transaction and calculation that generated it.

Best Practices¶

Do Not Edit Ledger Entries¶

The ledger is intended to be a historical record.

If a calculation is incorrect because of a configuration or transaction issue, the appropriate correction should preserve the original history rather than silently changing the existing ledger entry.

Do Not Delete Historical Entries¶

Deleting a ledger entry would break the audit trail and could also make existing statements or payout records difficult to reconcile.

Use Reversals for Cancelled Transactions¶

When a source Sales Invoice is cancelled, the application records the reversal separately from the original commission.

Treat the Ledger as the Calculation Record¶

The Commission Ledger should be considered the authoritative record of the commission calculation that occurred at the time of processing.

Next Step¶

Commission Ledger entries can be grouped into period-based Commission Statements for review, approval, and eventual payout.

Continue with Commission Statements.