Revenue Items

Executive Summary

Purpose & Scope

• Track revenue from deals including gross amounts, commission calculations, and recognition schedules
• Scope includes: Revenue item creation from Deal Engine sales blocks, commission calculations, recognition schedules, billing item generation
• Out of scope: Revenue posting to GL (future), revenue forecasting

Objectives

• Maintain accurate revenue records for each sales item from deals
• Support multiple revenue recognition styles (Immediate, Monthly, Completion)
• Generate billing items (receivables) from revenue payment terms
• Enable updates and revisions when deal terms change

Process Overview

Revenue Item Lifecycle

flowchart TD
    DE[Deal Engine] -->|Sales Block| SB[Sales Block Processing]
    SB -->|Create| RI[Revenue Item]
    RI -->|Payment Terms| BI[Billing Items]
    RI --> SCH[Revenue Schedules]
    
    DE -->|Update| UPD{Has Changes?}
    UPD -->|Yes| REV[Revise Revenue Item]
    UPD -->|No| SKIP[No Action]
    REV --> BI
    
    SCH --> POST[Post to GL]

Figure 1: Revenue Item Lifecycle from Deal Engine

Core Rules & Requirements

Revenue Item Structure

Component	Description
Header	Client, buyer, deal, gross amount, commission
Schedules	Periodic revenue recognition amounts
Billing Items	Receivables generated from payment terms

---

Status Codes

Item Status (revenue_item_status_cd)

Status	Code	Description
Unconfirmed	U	Preliminary, dates/amounts not final
Confirmed	C	Dates and amounts finalized
Modified	M	Has been revised

Date Status (revenue_item_date_status_cd)

Status	Code	Description
Unconfirmed	U	Start/end dates not confirmed
Confirmed	C	Dates confirmed

---

Commission Calculation

Type	Indicator	Calculation
Percentage	commission_flat_ind = false	Gross × Commission %
Flat	commission_flat_ind = true	Fixed commission amount

Commission Amount = Gross Amount × Commission Percentage
   OR
Commission Amount = Flat Amount (if flat indicator set)

---

Recognition Styles

Style	Code	Description
Immediate	I	Full commission recognized on start date
Monthly	M	Commission spread evenly across months
Completion	C	Full commission recognized on end date

Schedule Generation:

• Immediate: Single schedule entry for start date
• Monthly: Multiple entries from start to end, equal portions
• Completion: Single schedule entry for end date

---

Sales Block Sync Rules

Revenue items are created and updated via Sales Block Processing:

1. New Sales Item: Create revenue item + schedules + billing items
2. Updated Sales Item:
   • Match by sales_item_ref
   • Compare fields for changes
   • If changed: create reversal + new item
   • If unchanged: no action
3. Immutable Fields: If these change, full reversal required:
   • sales_item_ref, deal_id, uta_entity_id, client_id, buyer_id, currency_cd

---

Current Item Indicator

current_item_ind tracks active version:

Value	Meaning
true	This is the current/active version
false	This is a historical or reversed version

When revisions occur, old item is marked false, new item marked true.

User Interface Specifications

Revenue Items Page

Purpose: Search and view revenue items.

Search Criteria:

• Client
• Buyer
• Deal
• Status (Unconfirmed/Confirmed/Modified)
• Date Range
• Amount Range

Results Grid:

Column	Description
Revenue Item ID	Unique identifier
Sales Item Ref	Reference from Deal Engine
Name	Revenue item name
Deal	Associated deal
Client	Client party
Buyer	Buyer party
Gross Amount	Total gross
Commission %	Commission percentage
Commission Amt	Calculated commission
Status	U / C / M
Recognition	I / M / C
Start Date	Revenue start
End Date	Revenue end

Actions:

• View Details
• View Schedules
• View Billing Items

---

Revenue Item Detail View

Header:

• Revenue Item ID, Name
• Sales Item Ref
• Deal, Client, Buyer
• UTA Entity, Department

Amounts:

Field	Value
Gross Amount
Commission Type	Flat / Percentage
Commission %
Commission Amount
Cash Collected	(calculated)

Dates:

Field	Value
Start Date
End Date
Date Status	Unconfirmed / Confirmed
Recognition Style	Immediate / Monthly / Completion

---

Revenue Schedules Tab

Columns:

Column	Description
Schedule ID	Unique identifier
Revenue Date	Recognition date
Revenue Amount	Amount for this period
Posting Status	U (Unposted) / P (Posted)
Posting Date	When posted to GL

---

Client Revenue Tab

Purpose: View revenue items for a specific client.

Displays filtered view of revenue items where client_id matches.

Data Requirements

Revenue Items Table (revenue_items)

Field Name	Data Type	Description
revenue_item_id (PK)	Serial	Unique identifier
uta_entity_id (FK)	Integer	UTA entity
agent_group_id	Integer	Agent group
sales_item_ref	String	Reference from Deal Engine
revenue_item_name	String	Description
revenue_item_status_cd	Enum	U, C, M
revenue_item_date_status_cd	Enum	U, C
deal_id (FK)	Integer	Associated deal
client_id (FK)	Integer	Client party
contracted_party_id (FK)	Integer	Contracted party
buyer_id (FK)	Integer	Buyer party
project_id	Integer	Project reference
department_id (FK)	Integer	Department
currency_cd	String	Currency code
revenue_item_gross_amt	Decimal	Gross amount
revenue_item_commission_flat_ind	Boolean	Flat commission flag
revenue_item_commission_perc	Decimal	Commission percentage
revenue_item_commission_amt	Decimal	Commission amount
revenue_item_start_dt	Date	Start date
revenue_item_end_dt	Date	End date
revenue_item_rec_style_cd	Enum	I, M, C
current_item_ind	Boolean	Is current version

---

Revenue Item Schedules Table (revenue_item_schedules)

Field Name	Data Type	Description
revenue_item_schedule_id (PK)	Serial	Unique identifier
revenue_item_id (FK)	Integer	Parent revenue item
revenue_amt	Decimal	Amount for this period
revenue_dt	Date	Recognition date
revenue_item_posting_status_cd	Enum	U, P
revenue_item_posting_dt	Date	GL posting date

See Also

Document	Relationship
Billing Items	Generated from revenue payment terms
Sales Block Processing	Creates/updates revenue items

Gherkin Scenarios

Scenario: Create Revenue Item from Sales Block

Feature: Revenue Item Creation

  Scenario: Sales block creates new revenue item
    Given a new sales item from Deal Engine
    With gross amount $100,000
    And commission percentage 10%
    And recognition style "Monthly"
    And start date 2026-01-01 and end date 2026-12-31
    
    When Sales Block Processing runs
    
    Then a new revenue item should be created
    And commission amount should be $10,000
    And 12 revenue schedules should be created
    And each schedule should have amount $833.33
    And billing items should be created from payment terms

Scenario: Monthly Revenue Schedule Generation

Feature: Revenue Schedule Generation

  Scenario: Monthly recognition splits commission evenly
    Given a revenue item with:
      | Commission Amount | $12,000 |
      | Start Date | 2026-01-01 |
      | End Date | 2026-12-31 |
      | Recognition Style | Monthly |
    
    When schedules are generated
    
    Then 12 schedule entries should exist
    And each entry should have amount $1,000
    And dates should be first of each month

Scenario: Revenue Item Revision

Feature: Revenue Item Revision

  Scenario: Deal update triggers revenue item revision
    Given an existing revenue item for sales_item_ref "SI-001"
    With gross amount $100,000
    
    When Deal Engine sends update for "SI-001"
    With new gross amount $120,000
    
    Then the original revenue item should have current_item_ind = false
    And a new revenue item should be created with gross $120,000
    And new schedules and billing items should be generated

Scenario: Immediate Recognition

Feature: Immediate Recognition

  Scenario: Single schedule for immediate style
    Given a revenue item with recognition style "Immediate"
    And commission amount $10,000
    And start date 2026-03-15
    
    When schedules are generated
    
    Then exactly 1 schedule entry should exist
    And the schedule date should be 2026-03-15
    And the schedule amount should be $10,000