Client Ledger

Executive Summary

Purpose & Scope

• Track and manage client on-account balances and loan advances
• Scope includes: On-Account (OA) credits, loan advances, cash application integration, balance tracking
• Out of scope: Loan approval workflow (future), interest calculations

Objectives

• Maintain accurate client credit balances (on-account funds)
• Track loan advances to clients
• Enable application of on-account balances during cash receipt allocation
• Support balance drawdown and reconciliation

Process Overview

Client Ledger Lifecycle

flowchart TD
    Create[Create Ledger Entry] --> Type{Entry Type}
    Type --> OA[On-Account Entry]
    Type --> LOAN[Loan Entry]
    
    OA --> Posted[Post to GL]
    LOAN --> Posted
    
    Posted --> Available[Balance Available]
    Available --> Apply[Apply to Worksheet]
    Apply --> Reduced[Balance Reduced]
    Reduced -->|Has Balance| Available
    Reduced -->|Zero Balance| Closed[Entry Closed]

Figure 1: Client Ledger Entry Lifecycle

Core Rules & Requirements

Entry Types

Type	Code	Description	Use Case
On-Account	OA	Client credit balance	Overpayment, prepayment
Loan	LOAN	Advance to client	Commission advance, float

---

Status Lifecycle

Status	Code	Description
Draft	D	Entry created, not posted
Valid	V	Posted, balance available
Closed	C	Balance fully applied/reversed

---

Posting Status

Status	Code	Description
Unposted	U	Not posted to GL
Posted	P	Posted to GL
Cancelled	X	Reversed/cancelled

---

Balance Tracking

Remaining Balance = Original Amount - Sum(Applied Amounts)

Field	Description
client_ledger_amt	Original entry amount
appliedAmt	Total applied via worksheets
remainingAmt	Available balance

When remainingAmt reaches zero, client_ledger_open_item_ind becomes false and status changes to C (Closed).

---

Cash Application Integration

Client ledger entries can be applied during cash receipt allocation:

1. User adds client ledger item to worksheet
2. System creates cash_receipt_client_ledger record
3. Upon worksheet approval, client ledger balance is reduced
4. Worksheet return/reversal restores the balance

IMPORTANT

Client ledger applications follow the same approval workflow as receivable applications. They are not deducted until the worksheet is approved.

---

Reversal Rules

Scenario	Action
Worksheet returned	Restore ledger balance, create reversal record
Entry cancelled	Mark as X, restore any applied amounts

Reversal records track the original entry via reversal_of_ledger_id.

User Interface Specifications

Client Ledger Tab (Client Screen)

Purpose: View and manage client ledger entries for a specific client.

Columns:

Column	Description
Entry ID	Unique identifier
Name	User-entered description
Type	On-Account / Loan
Amount	Original amount
Balance	Remaining amount
Currency	Entry currency
Status	D / V / C
Deal	Associated deal (optional)
Start/End Date	Entry validity period
Notes	User notes

Actions:

• Add New Entry
• Edit (Draft only)
• View Details

---

Add/Edit Client Ledger Dialog

Fields:

Field	Type	Required	Notes
Entry Type	Dropdown	Yes	OA, LOAN
Name	Text	Yes	Description
Amount	Decimal	Yes	Must be > 0
Currency	Dropdown	Yes	Default: USD
Deal	Autocomplete	No	Optional association
Start Date	Date	No	When entry becomes valid
End Date	Date	No	When entry expires
Notes	Textarea	No	Additional details

Validations:

• Amount must be positive
• Currency required
• Name required

---

Client Ledger Selection (Worksheet)

Purpose: Add on-account or loan entries to a cash receipt worksheet.

Search Criteria:

• Client
• Deal
• Entry Type (OA/LOAN)
• Open Items Only (default: true)
• Amount Range

Results Grid:

Column	Description
Entry ID	Ledger entry ID
Client	Client name
Type	OA / LOAN
Deal	Associated deal
Original Amount	Entry amount
Applied	Already applied
Available	Remaining balance
Select	Checkbox or amount input

Actions:

• Select and add to worksheet
• Specify amount to apply (partial or full)

Data Requirements

Client Ledger Table (client_ledger)

Field Name	Data Type	Description
client_ledger_id (PK)	Serial	Unique identifier
client_id (FK)	Integer	Client party
contracted_party_id (FK)	Integer	Contracted party (optional)
buyer_id (FK)	Integer	Buyer (optional)
deal_id (FK)	Integer	Associated deal (optional)
uta_entity_id (FK)	Integer	UTA entity
department_id (FK)	Integer	Department
client_ledger_type_cd	Enum	OA, LOAN
client_ledger_status_cd	Enum	D, V, C
client_ledger_name	String	Entry description
client_ledger_amt	Decimal	Original amount
client_ledger_currency_cd	String	Currency code
client_ledger_start_dt	Date	Start date
client_ledger_end_dt	Date	End date
client_ledger_notes	String	Notes
client_ledger_open_item_ind	Boolean	Has open balance
client_ledger_payment_item_id	Integer	Source payment item
posting_status_cd	Enum	U, P, X
posting_dt	Date	GL posting date

---

Cash Receipt Client Ledger Table (cash_receipt_client_ledger)

Field Name	Data Type	Description
cash_receipt_client_ledger_id (PK)	Serial	Unique identifier
cash_receipt_worksheet_id (FK)	Integer	Worksheet applying this entry
client_ledger_id (FK)	Integer	Client ledger entry
deal_id (FK)	Integer	Deal context
uta_entity_id (FK)	Integer	UTA entity
department_id (FK)	Integer	Department
client_id (FK)	Integer	Client
cash_receipt_amt_applied	Decimal	Amount being applied
reversal_of_ledger_id	Integer	Original if reversal
reversal_reason_cd	String	Reason code

See Also

Document	Relationship
Cash Management	Worksheets apply client ledger entries
Payments	One-off payments sourced from client ledger

Gherkin Scenarios

Scenario: Create On-Account Entry

Feature: Client Ledger Entry Creation

  Scenario: User creates an on-account entry for a client
    Given I am on the Client Ledger tab for "John Smith"
    
    When I click "Add New Entry"
    And I select type "On-Account"
    And I enter name "Overpayment from Studio A"
    And I enter amount 5000.00
    And I select currency "USD"
    And I click "Save"
    
    Then a new client ledger entry should be created
    And status should be "Draft"
    And open_item_ind should be true

Scenario: Apply Client Ledger to Worksheet

Feature: Client Ledger Application

  Scenario: User applies on-account balance to cash worksheet
    Given Client "John Smith" has on-account balance of $5,000
    And I am on a cash receipt worksheet for "John Smith"
    
    When I click "Add On-Account"
    And I select the $5,000 on-account entry
    And I enter apply amount $2,000
    And I add to worksheet
    
    Then the worksheet should show $2,000 on-account application
    And the entry should still have $3,000 available until approved

Scenario: Worksheet Approval Reduces Balance

Feature: Balance Reduction on Approval

  Scenario: Balance is reduced when worksheet is approved
    Given a worksheet with $2,000 applied from client ledger entry
    
    When the worksheet is approved
    
    Then the client ledger entry balance should be reduced by $2,000
    And if balance reaches zero, open_item_ind should be false

Scenario: Worksheet Return Restores Balance

Feature: Balance Restoration on Return

  Scenario: Balance is restored when worksheet is returned
    Given a worksheet with $2,000 applied from client ledger entry was approved
    
    When the worksheet is returned
    
    Then a reversal record should be created
    And the client ledger entry balance should be restored by $2,000
    And open_item_ind should be true if balance > 0