Statements

Executive Summary

Purpose & Scope

• Generate and manage PDF statements for clients, deals, settlements, AR aging, and invoices
• Scope includes: Client statements, settlement statements, deal statements, AR aging statements, invoice generation, S3 storage, statement history
• Out of scope: Statement delivery/email, external integrations beyond S3

Objectives

• Provide clients with accurate financial summaries for defined date ranges
• Enable on-demand and batch statement generation
• Track all generated statements with full audit history
• Support multiple statement formats based on use case

Process Overview

Statement Generation Flow

flowchart TD
    User[User Request] --> Type{Statement Type}
    Type --> CS[Client Statement]
    Type --> SS[Settlement Statement]
    Type --> DS[Deal Statement]
    Type --> AR[AR Aging Statement]
    Type --> INV[Invoice]
    
    CS --> Agg[Data Aggregation]
    SS --> Agg
    DS --> Agg
    AR --> Agg
    INV --> Agg
    
    Agg --> PDF[PDF Generation]
    PDF --> S3[Upload to S3]
    S3 --> DB[Record in Database]
    DB --> Download[Available for Download]

Figure 1: Statement Generation Flow

Statement Types

Client Statement

Purpose: Summary of all transactions for a client within a date range.

Field	Description
Client	Party receiving the statement
Date Range	From/To dates for transactions
Currency	Statement currency
Transactions	List of payment items with gross, commission, net
Totals	Total gross, commission, and net amounts

Use Case: Regular reporting to clients on their account activity.

---

Settlement Statement

Purpose: Summary of settlements processed for a client.

Field	Description
Client	Party receiving settlements
Date Range	Period covered
Engagements	List of deals/venues with settlement amounts
Totals	Guarantee, overage, backout, net gross, commission due

Use Case: Showing clients how their earnings were settled.

---

Deal Statement

Purpose: Detailed breakdown of a specific deal's financials.

Field	Description
Deal	Deal reference and name
Revenue Items	All revenue items for the deal
Payees	Allocation percentages for each participant
Totals	Gross, commission, net by payee

Use Case: Deal-specific financial reporting.

---

AR Aging Statement

Purpose: Open receivables grouped by aging buckets.

Field	Description
Client (optional)	Filter by specific client
As-Of Date	Date to calculate aging from
Aging Buckets	Current, 30, 60, 90, 120+ days
Line Items	Billing items with invoice, due date, balance, age
Summary	Totals by aging bucket

Use Case: Collections prioritization and client AR health check.

---

Invoice

Purpose: Formal invoice document for billing items.

Field	Description
Party	Client or buyer being invoiced
Target Type	CLIENT or BUYER
Billing Items	Selected items to include
UK Entity Flag	Different format for UK regulations

Use Case: Formal billing documentation.

Core Rules & Requirements

Statement Reference Format

Type	Format	Example
Client Statement	CS-{timestamp}-{uuid}	CS-1736776800000-A1B2C3D4
Settlement Statement	SS-{timestamp}-{uuid}	SS-1736776800000-E5F6G7H8
Deal Statement	DS-{timestamp}-{uuid}	DS-1736776800000-I9J0K1L2
AR Aging	AR-{timestamp}-{uuid}	AR-1736776800000-M3N4O5P6
Invoice	INV-{timestamp}-{uuid}	INV-1736776800000-Q7R8S9T0

---

Generation Status Lifecycle

Status	Code	Description
Pending	PENDING	Request received, not started
Generating	GENERATING	PDF creation in progress
Completed	COMPLETED	Successfully generated and stored
Failed	FAILED	Error during generation

---

Storage Rules

• All statements are stored in S3 upon successful generation
• Database record created with S3 bucket/key reference
• Metadata (totals, counts) stored as JSON for quick retrieval
• Statements are immutable once generated

---

Data Filters

Statement Type	Required Filters	Optional Filters
Client Statement	clientId, dateFrom, dateTo	currencyCd, excludedPaymentItemIds
Settlement Statement	clientId, dateFrom, dateTo	currencyCd
Deal Statement	dealId	-
AR Aging	-	clientId, asOfDate, openItemsOnly
Invoice	partyId, targetType, billingItemIds	isUKEntity

User Interface Specifications

Statement Generation Screen

Fields:

• Statement Type (dropdown): Client, Settlement, Deal, AR Aging, Invoice
• Client (autocomplete): For client/settlement statements
• Deal (autocomplete): For deal statements
• Date From / Date To: Date range picker
• Currency (dropdown): USD, GBP, EUR, etc.

Actions:

• Preview (show data without generating PDF)
• Generate (create PDF and store)

---

Statement History Screen

Search Criteria:

• Client
• Statement Type
• Date Range (generated date)

Results Grid:

Column	Description
Statement Ref	Unique identifier link
Type	CLIENT_STATEMENT, etc.
Client	Party name
Date Range	From - To
Generated By	User who created
Generated Date	Timestamp
File Size	Size in KB
Actions	Download, View

---

Statement Preview

Purpose: View transactions before generating PDF.

Displays:

• Client information
• Transaction list (searchable/sortable)
• Totals summary
• "Generate PDF" button

Data Requirements

All tables have tracking for creation, last update, and user.

Generated Statement Table (generated_statement)

Field Name	Data Type	Description
generated_statement_id (PK)	Serial	Unique identifier
statement_type_cd	String	CLIENT_STATEMENT, SETTLEMENT_STATEMENT, etc.
statement_ref	String	Unique reference shown on PDF
client_id (FK)	Integer	Party this statement is for
date_from	Date	Start of covered period
date_to	Date	End of covered period
currency_cd	String	Statement currency
s3_bucket	String	S3 bucket name
s3_key	String	S3 object key
file_path	String	Local file path (dev only)
file_name	String	Original filename
file_size_bytes	Integer	File size
generation_status_cd	Enum	PENDING, GENERATING, COMPLETED, FAILED
error_message	Text	Error details if failed
metadata	JSONB	Flexible data (totals, counts, etc.)
generated_by	String	User who generated
generated_dt	DateTime	Generation timestamp

---

Statement Type Codes

Code	Description
CLIENT_STATEMENT	Client transaction summary
SETTLEMENT_STATEMENT	Settlement summary
DEAL_STATEMENT	Deal financial breakdown
AR_STATEMENT	AR aging report
INVOICE	Formal invoice

See Also

Document	Relationship
Cash Management	Payment items included in statements
Billing Items	Source for invoice line items
AR Aging	Dedicated AR aging requirements

Gherkin Scenarios

Scenario: Generate Client Statement

Feature: Client Statement Generation

  Scenario: User generates a client statement for a date range
    Given I am a Client Accounting user
    And Client "John Smith" has 5 payment items posted between 2026-01-01 and 2026-01-31
    
    When I select statement type "Client Statement"
    And I select client "John Smith"
    And I set date range to 2026-01-01 through 2026-01-31
    And I click "Generate"
    
    Then a PDF should be created
    And the statement should contain 5 transactions
    And the statement should be stored in S3
    And a record should be created in generated_statement table
    And the statement should be available for download

Scenario: Preview Before Generate

Feature: Statement Preview

  Scenario: User previews transactions before generating statement
    Given Client "Jane Doe" has transactions in the selected date range
    
    When I click "Preview"
    
    Then I should see a list of transactions
    And I should see the calculated totals
    And I should NOT yet have a PDF generated

Scenario: Download Historical Statement

Feature: Statement History

  Scenario: User downloads a previously generated statement
    Given a statement with ref "CS-1736776800000-ABC12345" exists
    
    When I search for statements for Client "John Smith"
    And I click "Download" on the statement row
    
    Then the PDF should be retrieved from S3
    And the file should download to my browser

Scenario: AR Aging for All Clients

Feature: AR Aging Statement

  Scenario: Generate AR aging for entire portfolio
    Given there are open billing items across multiple clients
    
    When I select statement type "AR Aging"
    And I leave client filter empty
    And I set as-of date to today
    And I click "Generate"
    
    Then a PDF should show all open receivables
    And receivables should be grouped by aging bucket
    And totals should be summarized by bucket