Billing Items

Executive Summary

Purpose & Scope

• Manage the lifecycle of billing items (receivables) that represent amounts to be collected from clients or buyers
• Scope includes: Billing item creation from payment terms, REV/PAY detail split, deductions, revision/reversal, cash application integration, and write-off tracking
• Out of scope: Revenue recognition (see revenue-recognition.md), cash receipt creation, write-off packet management (see write-offs.md)

Objectives

• Track receivables from deal payment terms through collection to close
• Maintain accurate split between Revenue (UTA commission) and Payable (client portion)
• Support deductions that adjust billing without changing base amounts
• Enable revision workflow when payment terms change from Deal Engine
• Integrate with cash application and write-off processes

Process Overview

Billing Item Lifecycle

flowchart LR
    DE[Deal Engine] -->|Payment Terms| BI[Billing Item Created]
    BI --> REV[REV Detail]
    BI --> PAY[PAY Detail]
    REV --> CA[Cash Application]
    PAY --> CA
    CA -->|Fully Paid| CLOSED[Closed]
    REV --> WO[Write-Off]
    WO --> CLOSED
    DE -->|Update| REVBI[Revise Billing Item]
    REVBI -->|Reversal + New| BI

Figure 1: Billing Item Lifecycle Flow

Core Rules & Requirements

Billing Item Structure

Each billing item consists of:

Component	Description
Header	Client, buyer, deal, due date, currency, status
REV Detail	UTA's commission portion (Revenue)
PAY Detail	Client's payout portion (Payable)
Deductions	Adjustments attached to REV or PAY details

IMPORTANT

Every billing item MUST have exactly 2 detail records: one REV and one PAY.

---

Status Lifecycle

Billing Item Status (billing_item_status_cd)

Status	Code	Description
Unposted	U	Created, pending GL posting
Billed	B	Invoiced to client/buyer
Cancelled	X	Cancelled/reversed
Closed	C	Fully paid, no open balance

Posting Status (posting_status_cd) - applies to detail records

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

---

Amount Calculations

REV/PAY Split Logic:

REV Gross Amount = Payment Term Gross Amount
REV Percent = Commission Percentage
REV Amount = Gross × Percent

PAY Gross Amount = Payment Term Gross Amount (or 0 if CLIENT collection)
PAY Percent = 1 - Commission Percentage (or 0 if CLIENT collection)
PAY Amount = Gross × Percent

IMPORTANT

Collection Style Rule: If collection_style_cd = 'CLIENT', all PAY amounts are set to zero. UTA collects from the client directly, and there is no buyer payout component.

---

Collection Style

Style	Code	Description
Buyer	BUYER	Collect from buyer → Split REV/PAY
Client	CLIENT	Collect from client → PAY amounts = 0

Default Logic: If collection_party_id matches buyer_id, style is BUYER; otherwise CLIENT.

Override: Users can manually override collection style via collection_style_override_ind = true.

---

Deductions

Deductions are adjustments attached to billing item details (REV or PAY) that represent withholdings, adjustments, or other modifications.

Field	Description
billing_item_deduction_type_cd	Type of deduction
billing_item_deduction_amt	Deduction amount
billing_item_deduction_update_net_ind	Whether to update net (legacy)
comment	User explanation

NOTE

Deductions do NOT affect billing_item_detail_amt. They are tracked separately and applied during cash receipt allocation.

---

Open Item Indicator

open_item_ind determines whether a billing item has outstanding balance:

Value	Condition
true	REV or PAY detail has remaining balance
false	Both REV and PAY fully applied (cash + deductions)

Balance Calculation:

Balance = Total Amount - Cash Applied

When both REV Balance and PAY Balance reach zero, open_item_ind is set to false.

---

Revision Workflow

When Deal Engine sends updated payment terms, billing items may need revision:

1. Match Check: Find existing billing item by payment_term_ref
2. Change Detection: Compare amounts, dates, collection party
3. If Changes Detected:
   • Create reversal record (negated amounts, current_item_ind = false)
   • Create new billing item with updated values
   • Transfer cash receipt applications to new item
   • Deactivate original (current_item_ind = false)
4. No Changes: No action required

Immutable Fields (changes require reversal):

• gross_amt, commission_amt, due_dt
• collection_party_id (if not overridden)

---

Write-Off Integration

Billing item details can be written off via Write-Off Packets:

Field	Description
write_off_packet_id	FK to packet (null if not written off)
write_off_status_cd	NOT_WRITTEN_OFF, WRITTEN_OFF, RECOVERED
write_off_dt	Timestamp of write-off
recovered_dt	Timestamp of recovery (if applicable)
exclude_from_cecl_ind	Exclude from CECL reporting when written off

NOTE

Only REV-type details can be written off. PAY details remain unchanged (company absorbs the loss).

User Interface Specifications

Billing Items Table

Location: Revenue page, Client tab

Columns:

• Billing Item ID
• Revenue Item Name
• Deal Name
• Client / Buyer
• Invoice #
• Due Date
• Gross Amount
• REV Amount / PAY Amount
• Cash Applied
• Balance
• Status
• Open Item Indicator

Actions:

• View Details
• Add Deduction (if open)
• Split Billing (worksheet context)

---

Billing Item Detail View

Header Section:

• Billing Item ID, Name
• Deal, Client, Buyer
• Collection Party / Style
• Due Date / Aging Date
• Currency
• Status

REV/PAY Breakdown:

	REV	PAY
Gross Amount
Percent
Amount
Tax
Total
Cash Applied
Balance

Deductions Table:

• Deduction Type
• Amount
• Applied Amount
• Balance
• Comment
• Actions: Edit, Delete

---

Deduction Dialog

Fields:

• Deduction Type (dropdown)
• Amount (decimal, required, > 0)
• Comment (text, optional)

Actions:

• Save
• Cancel

Data Requirements

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

Billing Item Table (billing_item)

Field Name	Data Type	Description
billing_item_id (PK)	Serial	Unique identifier
revenue_item_id (FK)	Integer	Reference to revenue item
payment_term_ref	String	Reference from Deal Engine
deal_id (FK)	Integer	Reference to deal
uta_entity_id (FK)	Integer	UTA entity
department_id (FK)	Integer	UTA department
client_id (FK)	Integer	Client party
buyer_id (FK)	Integer	Buyer party
collection_party_id (FK)	Integer	Party to collect from
collection_style_cd	Enum	BUYER, CLIENT
collection_style_override_ind	Boolean	Manual style override flag
billing_item_name	String	Description
billing_item_currency_cd	String	Currency code
billing_item_due_dt	Date	Due date
billing_item_due_dt_status_cd	Enum	U (Unpaid), C (Confirmed)
billing_item_aging_dt	Date	Aging date (defaults to due date)
billing_item_status_cd	Enum	U, B, X, C
invoice_id (FK)	Integer	Reference to invoice
current_item_ind	Boolean	Is this the current version
open_item_ind	Boolean	Has outstanding balance

---

Billing Item Detail Table (billing_item_detail)

Field Name	Data Type	Description
billing_item_detail_id (PK)	Serial	Unique identifier
billing_item_id (FK)	Integer	Parent billing item
billing_item_detail_type_cd	Enum	REV or PAY
billing_item_detail_gross_amt	Decimal	Gross amount
billing_item_detail_percent	Decimal	Commission percentage
billing_item_detail_amt	Decimal	Calculated amount (Gross × Percent)
billing_item_detail_tax_amt	Decimal	Tax amount
billing_item_detail_total_amt	Decimal	Total (Amount + Tax)
posting_status_cd	Enum	U, P, X
posting_dt	Date	GL posting date
write_off_packet_id (FK)	UUID	Write-off packet reference
write_off_status_cd	Enum	NOT_WRITTEN_OFF, WRITTEN_OFF, RECOVERED
write_off_dt	DateTime	Write-off timestamp
recovered_dt	DateTime	Recovery timestamp
exclude_from_cecl_ind	Boolean	Exclude from CECL reporting

---

Billing Item Deduction Table (billing_item_deduction)

Field Name	Data Type	Description
billing_item_deduction_id (PK)	Serial	Unique identifier
billing_item_detail_id (FK)	Integer	Parent detail record
billing_item_deduction_type_cd	Enum	Deduction type
billing_item_deduction_update_net_ind	Boolean	Legacy flag
billing_item_deduction_amt	Decimal	Deduction amount
comment	String	Explanation

---

Validations

Rule	Context	Enforcement
Exactly 2 details per billing item (REV + PAY)	Creation	Service Layer
Gross amounts sum must match revenue item	Cross-validation	Service Layer
Deduction amount must be positive	Deduction	API Schema
Collection style must be valid code	Billing Item	Database

See Also

Document	Relationship
Revenue Items	Parent entity - billing items created from revenue payment terms
Cash Management	Cash receipts applied to billing item details
Write-Offs	Write-off packets reference billing item details
Sales Block Processing	How Deal Engine updates create/revise billing items

Gherkin Scenarios

Scenario: Create Billing Item from Payment Term

Feature: Billing Item Creation

  Scenario: System creates billing item with REV and PAY details
    Given a revenue item with commission percentage 10%
    And a payment term with gross amount $10,000
    And collection party is the buyer
    
    When the system creates a billing item
    
    Then a billing item should be created with status "U"
    And a REV detail should exist with:
      | Gross Amount | $10,000 |
      | Percent      | 10%     |
      | Amount       | $1,000  |
    And a PAY detail should exist with:
      | Gross Amount | $10,000 |
      | Percent      | 90%     |
      | Amount       | $9,000  |
    And open_item_ind should be true

Scenario: CLIENT Collection Style Zeroes PAY

Feature: Collection Style Rules

  Scenario: PAY amounts are zero when collection style is CLIENT
    Given a revenue item with commission percentage 10%
    And a payment term with gross amount $10,000
    And collection party is the client
    
    When the system creates a billing item
    
    Then collection_style_cd should be "CLIENT"
    And PAY detail amounts should all be zero
    And REV detail amounts should be calculated normally

Scenario: Revise Billing Item When Payment Term Changes

Feature: Billing Item Revision

  Scenario: Payment term amount changes trigger revision
    Given an existing billing item for payment term "PT-001"
    With gross amount $10,000
    
    When Deal Engine sends updated payment term "PT-001"
    With gross amount $12,000
    
    Then a reversal billing item should be created
    With negated amounts from original
    And a new billing item should be created
    With gross amount $12,000
    And cash applications should transfer to new item
    And original billing item current_item_ind should be false

Scenario: Close Billing Item When Fully Paid

Feature: Billing Item Closure

  Scenario: Billing item closes when all balances are zero
    Given a billing item with:
      | REV Total | $1,000 |
      | PAY Total | $9,000 |
    
    When cash is applied:
      | REV Applied | $1,000 |
      | PAY Applied | $9,000 |
    
    Then open_item_ind should be false
    And the billing item should be considered closed