Skip to content

Ledger Functions

The Ledger tracks all financial transactions for audit trails, reporting, and regulatory compliance.

Overview

The Ledger is an array of transaction entries that records:

  • Every premium calculation component
  • Adjustments and modifications
  • Cancellation refunds
  • Fees and charges

Each ledger entry captures:

  • Transaction description
  • Net, commission, tax amounts
  • Gross total
  • Currency
  • Ledger section (Policy, Fee, AddOn, etc.)

$AddToLedger

Adds a transaction entry to the ledger.

Signature

$AddToLedger(ledgerType, ledgerSubType, ledgerSection, netAmount, commissionAmount, taxAmount, taxRate, taxType, grossAmount, currency, isRefundable)

Parameters

  • ledgerType (string) - Ledger type: "Policy", "Fee", "AddOn", "MTA", "Cancellation"
  • ledgerSubType (string) - Entry subtype: "Regular", "Factor", "Discount", "Item", "Cancellation"
  • ledgerSection (string) - Transaction description/section name
  • netAmount (number) - Net premium amount
  • commissionAmount (number) - Commission amount
  • taxAmount (number) - Tax/IPT amount
  • taxRate (number) - Tax rate as decimal (e.g., 0.12)
  • taxType (string) - Tax type: "IPT", "Duty", "Tax"
  • grossAmount (number) - Gross total
  • currency (string) - ISO currency code
  • isRefundable (boolean) - True if this entry is refundable (not a reversal flag)

Returns

  • Updated Ledger array

Example

// Manual ledger entry
$AddToLedger(
    "Policy",           // ledgerType
    "Item",             // ledgerSubType
    "Manual Premium",   // ledgerSection (description)
    500.00,             // netAmount
    75.00,              // commissionAmount
    69.00,              // taxAmount
    0.12,               // taxRate (12%)
    "IPT",              // taxType
    644.00,             // grossAmount
    "GBP",              // currency
    true                // isRefundable
);

// Ledger now contains one entry
let totalGross = $Sum($Map(Ledger, fn(entry) => entry.GrossAmount));

Ledger Structure

Entry Fields

Each ledger entry is an object with these properties:

{
    LedgerType: "Policy",            // Type grouping
    LedgerSubType: "Item",           // Entry subtype
    LedgerSection: "Base Premium",   // Description/section name
    NetAmount: 500.00,               // Net premium
    CommissionAmount: 75.00,         // Commission
    TaxAmount: 69.00,                // Tax/IPT
    TaxRate: 0.12,                   // Tax rate
    TaxType: "IPT",                  // Tax classification
    GrossAmount: 644.00,             // Total
    Currency: "GBP",                 // Currency
    IsRefundable: true               // Refundable flag
}

Automatic Ledger Population

Most Quote Extension functions automatically populate the ledger:

$CalculatePremiumAdditive

Clears and rebuilds the ledger with all pricing matrix calculations:

$SetCurrencyToPricingMatrix("GBP");
$AddItemToPricingMatrix("Base Premium", 500.00, 1.0);
$AddFactorToPricingMatrix("Age Factor", 1.20, true, 0);
$SetFeeToPricingMatrix(20.00);

$CalculatePremiumAdditive("NewBusiness");

// Ledger now contains entries for:
// - Base Premium item
// - Age Factor adjustment
// - Admin Fee
// Each with calculated net, commission, IPT, and gross

$CalculateMTAPremium

Populates ledger with adjustment entries:

$CalculateMTAPremium(25.00);

// Ledger contains:
// - MTA Fee entry
// - Pro-rata adjustment entries
// - Difference calculations

Cancellation Functions

Populate ledger with refund entries:

$CalculateProRataCancellation(25.00, false);

// Ledger contains:
// - Cancellation fee entry
// - Pro-rata refund calculations by section
// - Net refund amounts

Ledger Analysis

Accessing Entries

// Get all entries
let allEntries = Ledger;

// Filter by section
let policyEntries = $Filter(Ledger, fn(e) => e.LedgerSection == "Policy");
let feeEntries = $Filter(Ledger, fn(e) => e.LedgerSection == "Fee");

// Filter by type
let itemEntries = $Filter(Ledger, fn(e) => e.EntryType == "Item");
let factors = $Filter(Ledger, fn(e) => e.EntryType == "Factor");

Calculating Totals

// Total gross premium
let totalGross = $Sum($Map(Ledger, fn(e) => e.GrossAmount));

// Total net (before commission)
let totalNet = $Sum($Map(Ledger, fn(e) => e.NetAmount));

// Total IPT
let totalIPT = $Sum($Map(Ledger, fn(e) => e.TaxAmount));

// Total commission
let totalCommission = $Sum($Map(Ledger, fn(e) => e.CommissionAmount));

Grouping Calculations

// Group by section and sum
let sections = ["Policy", "Fee", "AddOn"];
let sectionTotals = $Map(sections, fn(section) => {
    let entries = $Filter(Ledger, fn(e) => e.LedgerSection == section);
    let total = $Sum($Map(entries, fn(e) => e.GrossAmount));
    return { Section: section, Total: total };
});

Ledger History

For MTAs and cancellations, historical ledger data is used:

MTALedgerHistory

Contains the original ledger entries before the adjustment:

// Environment variable: MTALedgerHistory
let originalPremium = $Sum($Map(MTALedgerHistory, fn(e) => e.GrossAmount));

// Calculate MTA
$CalculateMTAPremium(15.00);

let newPremium = $Sum($Map(Ledger, fn(e) => e.GrossAmount));
let difference = newPremium - originalPremium;

Reversal Entries

Reversals negate previous transactions:

// Manually create a reversal (using negative amounts)
$AddToLedger(
    "Policy",
    "Item",
    "Reversal - Base Premium",
    -500.00,      // Negative amounts
    -75.00,
    -69.00,
    0.12,
    "IPT",
    -644.00,
    "GBP",
    false         // Not refundable (it's a reversal)
);

// Net effect: zeros out the original entry

Reporting Example

// Generate ledger summary report
fn GenerateLedgerReport() {
    let report = {
        TotalGross: $Sum($Map(Ledger, fn(e) => e.GrossAmount)),
        TotalNet: $Sum($Map(Ledger, fn(e) => e.NetAmount)),
        TotalCommission: $Sum($Map(Ledger, fn(e) => e.CommissionAmount)),
        TotalIPT: $Sum($Map(Ledger, fn(e) => e.TaxAmount)),
        EntryCount: $Count(Ledger),
        BySection: {}
    };

    let sections = ["Policy", "Fee", "AddOn"];
    for (let section in sections) {
        let entries = $Filter(Ledger, fn(e) => e.LedgerSection == section);
        report.BySection[section] = {
            Count: $Count(entries),
            Gross: $Sum($Map(entries, fn(e) => e.GrossAmount))
        };
    }

    return report;
}

let report = GenerateLedgerReport();
$Log("Ledger Report", report);

Integration with Output

The ledger data flows into the Output object:

$CalculatePremiumAdditive("NewBusiness");

// Output automatically populated from ledger totals
let finalPremium = Output.Premium;  // Sum of ledger gross amounts
let iptApplied = Output.IptApplied;  // IPT rate from pricing matrix

Best Practices

1. Let Functions Manage the Ledger

Prefer using $CalculatePremiumAdditive and related functions rather than manual $AddToLedger calls:

// ✅ Preferred
$CalculatePremiumAdditive("NewBusiness");

// ❌ Avoid (unless custom logic required)
$AddToLedger(...);  // Manual entries

2. Preserve Ledger History

For MTAs and adjustments, save the original ledger:

// Before MTA
let MTALedgerHistory = Ledger;  // Save original

// Perform MTA
$CalculateMTAPremium(15.00);

// Ledger now has new values, MTALedgerHistory preserves original

3. Use Consistent Section Names

Standard section names:

  • "Policy" - Main policy premium
  • "Fee" - Admin fees
  • "AddOn" - Optional coverages
  • "MTA" - Mid-term adjustments
  • "Cancellation" - Cancellation entries

4. Validate Ledger Totals

// Ensure ledger gross matches pricing matrix
let ledgerGross = $Sum($Map(Ledger, fn(e) => e.GrossAmount));
let matrixPremium = PricingMatrix.Premium;

if ($Abs(ledgerGross - matrixPremium) > 0.01) {
    $Log("Warning: Ledger mismatch");
}

Environment Variables

Variable Type Description
Ledger Array Current ledger entries
MTALedgerHistory Array Original ledger before MTA
Output Object Populated with ledger totals

Next Steps