Skip to content

Billing Items Queries

Data model reference: Billing Items Data Model

Tables covered: billing_item, billing_item_detail, billing_item_deduction, revenue_items, revenue_item_schedules


1. Executive Summary

The billing items domain provides the data retrieval operations that support receivable management, cash application, accounts receivable aging, tax withholding, and revenue recognition across Client Processing. At its core, this domain answers three fundamental questions:

  1. What is owed? — Billing items and their REV/PAY detail breakdown, enriched with party, deal, and entity context.
  2. What has been collected? — Cash applied and deductions applied against each billing item detail, computed from the cash application and worksheet tables.
  3. What remains? — Balance calculations that subtract cash applied and deductions applied from the billed total to produce outstanding receivable amounts.

The query surface spans five functional areas:

  • Single-record lookups — Retrieve a billing item, billing item detail, or billing item deduction by primary key.
  • List and search operations — Retrieve billing items filtered by revenue item, status, client, buyer, deal, department, currency, free-text search, and reference identifiers. These operations serve the receivable list page, the receivable search dialog within the worksheet, and the billing management UI.
  • Flattened display views — A composite query that joins billing_item with its REV and PAY detail rows side-by-side, enriches with party/deal/entity names, and computes balance, cash applied, and deduction totals using correlated subqueries. This is the primary read model for all receivable-facing UIs.
  • AR aging reports — Summary and detail views that classify outstanding balances into aging buckets (Current, 1–30, 31–60, 61–90, 90+) based on due date.
  • Revenue item queries — Retrieve revenue items and their recognition schedules, with computed cash-collected totals.

All monetary balance computations share a common pattern: they consider only applications and deductions on worksheets that are current (current_item_ind = true) and in an approved or submitted status (cash_receipt_worksheet_status_cd IN ('A', 'S')). This ensures that draft, returned, and superseded worksheets do not affect receivable balances.


2. Key Queries

2.1 Single-Record Lookups

2.1.1 Get Billing Item by ID

Operation: getBillingItemById

Input Parameters:

  • id: integer (required) — billing_item.billing_item_id

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_itemSingle-table select by primary key

Filters:

  • billing_item.billing_item_id = :id

Computed Values:

  • None

Returns: One billing_item row matching the primary key, or null if not found.


2.1.2 Get All Billing Items

Operation: getAllBillingItems

Input Parameters:

  • None

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_itemFull table scan

Filters:

  • None — returns all rows.

Computed Values:

  • None

Returns: All rows from billing_item with no filtering.


2.1.3 Get Current Billing Items by Revenue Item

Operation: getCurrentBillingItemsByRevenueItemId

Input Parameters:

  • revenueItemId: integer (required) — billing_item.revenue_item_id

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_itemSingle-table select with filters

Filters:

  • billing_item.revenue_item_id = :revenueItemId
  • billing_item.current_item_ind = true

Computed Values:

  • None

Returns: All current billing items linked to the specified revenue item, used during rebilling to find the active billing items for a deal's revenue.


2.1.4 Get Billing Item Detail by ID

Operation: getBillingItemDetailById

Input Parameters:

  • id: integer (required) — billing_item_detail.billing_item_detail_id

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_item_detailSingle-table select by primary key

Filters:

  • billing_item_detail.billing_item_detail_id = :id

Computed Values:

  • None

Returns: One billing_item_detail row or null.


2.1.5 Get Billing Item Details by Billing Item

Operation: getBillingItemDetailsByBillingItemId

Input Parameters:

  • billingItemId: integer (required) — billing_item_detail.billing_item_id

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_item_detailSingle-table select with filter

Filters:

  • billing_item_detail.billing_item_id = :billingItemId

Computed Values:

  • None

Returns: Typically two rows per billing item — one with billing_item_detail_type_cd = 'REV' and one with billing_item_detail_type_cd = 'PAY'.


2.1.6 Get Billing Item Deduction by ID

Operation: getBillingItemDeductionById

Input Parameters:

  • id: integer (required) — billing_item_deduction.billing_item_deduction_id

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_item_deductionSingle-table select by primary key

Filters:

  • billing_item_deduction.billing_item_deduction_id = :id

Computed Values:

  • None

Returns: One billing_item_deduction row or null.


2.2 Deduction Queries

2.2.1 Get Billing Item Deductions by Detail (with Applied Amounts)

Operation: getBillingItemDeductionsByDetailId

Input Parameters:

  • detailId: integer (required) — billing_item_deduction.billing_item_detail_id

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_item_deductionBase deduction records filtered by detail

Filters:

  • billing_item_deduction.billing_item_detail_id = :detailId

Computed Values:

  • deduction_applied_amt: correlated subquery — SUM(cash_receipt_application_deduction.deduction_amt_applied) across all applications for :detailId where cash_receipt_application_deduction.billing_item_deduction_type_cd matches the current row's type code, joined through cash_receipt_application and cash_receipt_worksheet, filtered to cash_receipt_application.billing_item_detail_id = :detailId, cash_receipt_worksheet.current_item_ind = true, cash_receipt_worksheet.cash_receipt_worksheet_status_cd IN ('A', 'S')
  • deduction_balance: billing_item_deduction.billing_item_deduction_amt - deduction_applied_amt (same correlated subquery subtracted from the billing amount)

Returns: All deduction rows for the specified detail, each enriched with how much of the deduction has been applied via cash receipt worksheets and the remaining deduction balance.


2.3 Billing Item Display (Flattened View)

2.3.1 Get Billing Items Display

Operation: getBillingItemsDisplay

Input Parameters:

  • searchTerm: string (optional) — case-insensitive pattern match across billing_item.billing_item_name, client.display_name, buyer.display_name, deal.deal_reference, deal.deal_name, revenue_items.sales_item_ref, billing_item.payment_term_ref
  • billingItemId: integer (optional) — billing_item.billing_item_id
  • billingItemIds: integer[] (optional) — billing_item.billing_item_id (IN list)
  • revenueItemId: integer (optional) — billing_item.revenue_item_id
  • revenueItemIds: integer[] (optional) — billing_item.revenue_item_id (IN list)
  • billingItemStatusCd: string (optional) — billing_item.billing_item_status_cd
  • currencyCd: string (optional) — billing_item.currency_cd (case-insensitive match)
  • openItemOnly: boolean (optional) — when true, billing_item.open_item_ind = true
  • currentItemOnly: boolean (optional) — when true, billing_item.current_item_ind = true
  • revenueItemDateStatusCd: string (optional) — revenue_items.revenue_item_date_status_cd
  • hideZeroBillings: boolean (optional, default: true) — when true, excludes rows where revDetail.billing_item_detail_gross_amt = 0
  • includeWrittenOff: boolean (optional, default: false) — when false, excludes rows where revDetail.write_off_status_cd = 'WRITTEN_OFF'
  • clientId: integer (optional) — billing_item.client_id
  • clientIds: integer[] (optional) — billing_item.client_id (IN list)
  • buyerId: integer (optional) — billing_item.buyer_id
  • buyerIds: integer[] (optional) — billing_item.buyer_id (IN list)
  • dealId: integer (optional) — billing_item.deal_id
  • dealIds: integer[] (optional) — billing_item.deal_id (IN list)
  • departmentId: integer (optional) — revenue_items.department_id
  • departmentIds: integer[] (optional) — revenue_items.department_id (IN list)
  • utaEntityId: integer (optional) — billing_item.uta_entity_id
  • collectionPartyIds: integer[] (optional) — billing_item.collection_party_id (IN list)
  • contractedPartyIds: integer[] (optional) — billing_item.contracted_party_id (IN list)
  • salesItemRefs: string[] (optional) — revenue_items.sales_item_ref (IN list)
  • paymentTermRefs: string[] (optional) — billing_item.payment_term_ref (IN list)
  • limit: integer (optional) — row limit
  • offset: integer (optional) — pagination offset

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_itemLEFTbilling_item_detail (as revDetail)revDetail.billing_item_id = billing_item.billing_item_id AND revDetail.billing_item_detail_type_cd = 'REV'REV detail side of the pivot
billing_itemLEFTbilling_item_detail (as payDetail)payDetail.billing_item_id = billing_item.billing_item_id AND payDetail.billing_item_detail_type_cd = 'PAY'PAY detail side of the pivot
billing_itemLEFTparty (as client)client.party_id = billing_item.client_idClient display name
billing_itemLEFTparty (as buyer)buyer.party_id = billing_item.buyer_idBuyer display name
billing_itemLEFTuta_entityuta_entity.uta_entity_id = billing_item.uta_entity_idUTA entity name
billing_itemLEFTdealdeal.deal_id = billing_item.deal_idDeal name and reference
billing_itemLEFTparty (as collectionParty)collectionParty.party_id = billing_item.collection_party_idCollection party name
billing_itemLEFTrevenue_itemsrevenue_items.revenue_item_id = billing_item.revenue_item_idRevenue item name and sales item ref
billing_itemLEFTdepartmentdepartment.department_id = billing_item.department_idDepartment name

Filters:

Filters are organized into three tiers, combined as: (Global Conditions) AND ( (Scope Conditions) OR (Reference Conditions) ).

  • Global Conditions (always AND-ed): searchTerm, billingItemId, billingItemIds, revenueItemId, revenueItemIds, billingItemStatusCd, currencyCd, openItemOnly, currentItemOnly, revenueItemDateStatusCd, hideZeroBillings, includeWrittenOff
  • Scope Conditions (AND-ed together): clientId, clientIds, buyerId, buyerIds, dealId, dealIds, departmentId, departmentIds, utaEntityId, collectionPartyIds, contractedPartyIds
  • Reference Conditions (OR-ed together): salesItemRefs, paymentTermRefs

When both Scope and Reference conditions are present, a billing item matches if it satisfies the Scope intersection OR matches any Reference condition.

Computed Values:

  • billingItemGrossAmt: COALESCE(revDetail.billing_item_detail_gross_amt, 0)
  • billingItemTaxAmt: COALESCE(revDetail.billing_item_detail_tax_amt, 0) + COALESCE(payDetail.billing_item_detail_tax_amt, 0)
  • totalDeductions: SUM(billing_item_deduction.billing_item_deduction_amt) for REV detail + same for PAY detail (correlated subqueries)
  • totalAppliedDeductions: SUM(cash_receipt_application_deduction.deduction_amt_applied) across both REV and PAY details on worksheets with status IN ('A','S') and current_item_ind = true
  • billingItemTotalAmt: COALESCE(revDetail.billing_item_detail_total_amt, 0) + COALESCE(payDetail.billing_item_detail_total_amt, 0)
  • revCash: SUM(cash_receipt_application.cash_receipt_amt_applied) for REV detail on worksheets with status = 'A' and current_item_ind = true (Approved only)
  • payCash: SUM(cash_receipt_application.cash_receipt_amt_applied) for PAY detail on worksheets with status = 'A' and current_item_ind = true (Approved only)
  • cashApplied: revCash + payCash (combined, Approved only)
  • balance: billingItemTotalAmt - totalAppliedDeductions(A/S) - cashApplied(A/S) where both deductions and cash use status IN ('A','S')
  • revBalance: revDetail.billing_item_detail_total_amt - revAppliedDeductions(A/S) - revCashApplied(A/S)
  • payBalance: payDetail.billing_item_detail_total_amt - payAppliedDeductions(A/S) - payCashApplied(A/S)
  • revDeductions: SUM(billing_item_deduction.billing_item_deduction_amt) for REV detail
  • revAppliedDeductions: SUM(cash_receipt_application_deduction.deduction_amt_applied) for REV detail on qualifying worksheets
  • revDeductionsBalance: revDeductions - revAppliedDeductions
  • payDeductions: SUM(billing_item_deduction.billing_item_deduction_amt) for PAY detail
  • payAppliedDeductions: SUM(cash_receipt_application_deduction.deduction_amt_applied) for PAY detail on qualifying worksheets
  • payDeductionsBalance: payDeductions - payAppliedDeductions
  • revPercent: COALESCE(revDetail.billing_item_detail_percent, 0)

Returns: One flattened row per billing item containing header fields, party/deal/entity enrichment, REV detail fields, PAY detail fields, aggregate balance fields, and audit fields, ordered by client.display_name ASC, deal.deal_name ASC, revenue_items.revenue_item_name ASC, billing_item.billing_item_due_dt ASC.


Variant: By Client ID

Operation: getBillingItemsDisplayByClientId

Additional filters:

  • billing_item.client_id = :clientId
  • billing_item.current_item_ind = true

All other aspects identical to 2.3.1.


Variant: By Billing Item ID

Operation: getBillingItemDisplayById

Additional filter:

  • billing_item.billing_item_id = :id

All other aspects identical to 2.3.1.


Variant: Search Receivables (Current Only)

Operation: searchReceivables

Additional filter:

  • billing_item.current_item_ind = true (always forced)

All other aspects identical to 2.3.1.


Variant: Search All Receivables (Including Historical)

Operation: searchAllReceivables

No additional forced filters — current_item_ind is not forced, allowing historical receivables to be returned when criteria do not specify it.

All other aspects identical to 2.3.1.


2.4 Cash Application Aggregates

2.4.1 Cash Receipt Amount Applied to Detail

Operation: getCashReceiptAmountForDetail

Input Parameters:

  • detailId: integer (required) — cash_receipt_application.billing_item_detail_id

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
cash_receipt_applicationINNERcash_receipt_worksheetcash_receipt_application.cash_receipt_worksheet_id = cash_receipt_worksheet.cash_receipt_worksheet_idFilter by worksheet status and currency flag

Filters:

  • cash_receipt_application.billing_item_detail_id = :detailId
  • cash_receipt_worksheet.cash_receipt_worksheet_status_cd IN ('A', 'S')
  • cash_receipt_worksheet.current_item_ind = true

Computed Values:

  • SUM(cash_receipt_application.cash_receipt_amt_applied) — total cash applied to this detail across all qualifying worksheets

Returns: A single numeric value representing total cash applied to the specified billing item detail on current approved or submitted worksheets.


2.4.2 Total Applied Amount for Detail (Cash + Deductions)

Operation: getTotalAppliedAmountForDetail

Input Parameters:

  • detailId: integer (required) — cash_receipt_application.billing_item_detail_id

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
cash_receipt_applicationINNERcash_receipt_worksheetcash_receipt_application.cash_receipt_worksheet_id = cash_receipt_worksheet.cash_receipt_worksheet_idQuery 1: filter cash applications by worksheet status
cash_receipt_application_deductionINNERcash_receipt_applicationcash_receipt_application_deduction.cash_receipt_application_id = cash_receipt_application.cash_receipt_application_idQuery 2: link deduction to its application
cash_receipt_applicationINNERcash_receipt_worksheetcash_receipt_application.cash_receipt_worksheet_id = cash_receipt_worksheet.cash_receipt_worksheet_idQuery 2: filter deduction's worksheet by status

Filters:

  • cash_receipt_application.billing_item_detail_id = :detailId (both queries)
  • cash_receipt_worksheet.cash_receipt_worksheet_status_cd IN ('A', 'S') (both queries)
  • cash_receipt_worksheet.current_item_ind = true (both queries)

Computed Values:

  • cashApplied: SUM(cash_receipt_application.cash_receipt_amt_applied) (Query 1)
  • deductionsApplied: SUM(cash_receipt_application_deduction.deduction_amt_applied) (Query 2)
  • total: cashApplied + deductionsApplied

Returns: A single numeric value representing the combined cash and deductions applied against the billing item detail, used during rebilling to determine whether applications need to be migrated to new detail records.


2.5 Billing Job Queries

2.5.1 Unposted Billing Item Details Up to Date

Operation: getUnpostedDetailsUpToDate

Input Parameters:

  • date: date (required) — upper bound for billing_item.billing_item_due_dt and billing_item_detail.created_dt

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_item_detailINNERbilling_itembilling_item_detail.billing_item_id = billing_item.billing_item_idAccess header fields for due date and date-status filters
billing_itemLEFTrevenue_itemsbilling_item.revenue_item_id = revenue_items.revenue_item_idRetrieve sales_item_ref for GL posting reference

Filters:

  • billing_item_detail.billing_item_detail_type_cd = 'REV' — only REV details are posted to GL
  • billing_item_detail.posting_status_cd = 'U' — unposted only
  • billing_item.billing_item_due_dt_status_cd = 'C' — confirmed due date
  • billing_item.billing_item_due_dt <= :date — due on or before the target date
  • billing_item_detail.created_dt <= :date (end of day) — created on or before the target date

Computed Values:

  • None

Returns: Each result contains a billing_item_detail record, its parent billing_item record, and the revenue_items.sales_item_ref (nullable), used by the billing posting job to find REV details ready for GL posting.


2.5.2 Reset Posted Details by Posting Date

Operation: resetDetailsPostedOnOrAfterDate

Input Parameters:

  • date: date (required) — lower bound for billing_item_detail.posting_dt

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_item_detailDirect update with filters

Filters:

  • billing_item_detail.billing_item_detail_type_cd = 'REV'
  • billing_item_detail.posting_status_cd = 'P'
  • billing_item_detail.posting_dt >= :date

Computed Values:

  • None — this is an UPDATE operation that sets posting_status_cd = 'U' and posting_dt = NULL

Returns: Count of rows reset, used by the billing posting job to undo REV detail postings on or after a given date.


2.5.3 Reset Posted Details by Due Date

Operation: resetDetailsWithDueDateOnOrAfter

Input Parameters:

  • date: date (required) — lower bound for billing_item.billing_item_due_dt

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_item_detailINNERbilling_itembilling_item_detail.billing_item_id = billing_item.billing_item_idStep 1: access due date to identify target detail IDs

Filters:

  • billing_item_detail.billing_item_detail_type_cd = 'REV'
  • billing_item_detail.posting_status_cd = 'P'
  • billing_item.billing_item_due_dt >= :date

Computed Values:

  • None — two-step operation: Step 1 selects qualifying billing_item_detail_id values; Step 2 updates those rows to set posting_status_cd = 'U' and posting_dt = NULL

Returns: Count of rows reset.


2.6 AR Aging Reports

2.6.1 AR Aging Summary

Operation: getArAgingSummary

Input Parameters:

  • clientId: integer (optional) — billing_item.client_id
  • buyerId: integer (optional) — billing_item.buyer_id
  • dealId: integer (optional) — billing_item.deal_id
  • departmentId: integer (optional) — billing_item.department_id
  • billingItemId: integer (optional) — billing_item.billing_item_id
  • currencyCd: string (optional) — billing_item.currency_cd
  • collectionStyleCd: string (optional) — billing_item.collection_style_cd
  • openItemOnly: boolean (optional) — when true, billing_item.open_item_ind = true
  • includeWrittenOff: boolean (optional) — when false, excludes revDetail.write_off_status_cd = 'WRITTEN_OFF'
  • dueDateFrom: date (optional) — billing_item.billing_item_due_dt >= :dueDateFrom
  • dueDateTo: date (optional) — billing_item.billing_item_due_dt <= :dueDateTo
  • searchTerm: string (optional) — case-insensitive pattern match on billing_item.billing_item_name, client.display_name, buyer.display_name, deal.deal_name

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_itemLEFTbilling_item_detail (as revDetail)revDetail.billing_item_id = billing_item.billing_item_id AND revDetail.billing_item_detail_type_cd = 'REV'REV detail for balance and commission fields
billing_itemLEFTbilling_item_detail (as payDetail)payDetail.billing_item_id = billing_item.billing_item_id AND payDetail.billing_item_detail_type_cd = 'PAY'PAY detail for gross amount
billing_itemLEFTparty (as client)client.party_id = billing_item.client_idClient display name
billing_itemLEFTparty (as buyer)buyer.party_id = billing_item.buyer_idBuyer display name
billing_itemLEFTdealdeal.deal_id = billing_item.deal_idDeal name
billing_itemLEFTdepartmentdepartment.department_id = billing_item.department_idDepartment name

Filters:

  • All input parameters are applied when provided
  • When includeWrittenOff is false (default): revDetail.write_off_status_cd IS NULL OR revDetail.write_off_status_cd != 'WRITTEN_OFF'

Computed Values:

  • daysOverdue: CURRENT_DATE - billing_item.billing_item_due_dt (NULL if no due date)
  • totalBalance: (revDetail.billing_item_detail_total_amt + payDetail.billing_item_detail_total_amt) - totalAppliedDeductions(A/S) - cashApplied(A/S) (correlated subqueries for each detail)
  • billingGrossAmt: payDetail.billing_item_detail_gross_amt — what the client pays
  • commissionPercent: revDetail.billing_item_detail_percent
  • revenueAmount: revDetail.billing_item_detail_total_amt
  • cashCollected: SUM(cash_receipt_application.cash_receipt_amt_applied) for both REV and PAY details on worksheets with status IN ('A','S') and current_item_ind = true
  • deductionTotal: SUM(billing_item_deduction.billing_item_deduction_amt WHERE billing_item_deduction_update_net_ind = true) for both REV and PAY details
  • netAfterDeductions: billingGrossAmt - deductionTotal
  • hasDeductions: EXISTS check for any billing_item_deduction rows on either REV or PAY detail
  • agingCurrent: totalBalance when billing_item_due_dt IS NULL OR billing_item_due_dt >= CURRENT_DATE, else 0
  • aging1to30: totalBalance when daysOverdue BETWEEN 1 AND 30, else 0
  • aging31to60: totalBalance when daysOverdue BETWEEN 31 AND 60, else 0
  • aging61to90: totalBalance when daysOverdue BETWEEN 61 AND 90, else 0
  • aging90Plus: totalBalance when daysOverdue > 90, else 0

Returns: One row per billing item containing party/deal context, combined REV+PAY balance, and the balance classified into exactly one aging bucket, ordered by department_name, deal_name, billing_item_due_dt.


2.6.2 AR Aging Detail

Operation: getArAgingDetail

Input Parameters:

  • Same parameters as AR Aging Summary — see 2.6.1

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_item_detailINNERbilling_itembilling_item_detail.billing_item_id = billing_item.billing_item_idAccess header fields; base table is detail not billing item
billing_itemLEFTparty (as client)client.party_id = billing_item.client_idClient display name
billing_itemLEFTparty (as buyer)buyer.party_id = billing_item.buyer_idBuyer display name
billing_itemLEFTdealdeal.deal_id = billing_item.deal_idDeal name
billing_itemLEFTdepartmentdepartment.department_id = billing_item.department_idDepartment name

NOTE

Unlike the Summary view, the Detail view does not use the REV/PAY alias pivot. billing_item_detail is the base table, producing separate rows for each detail type (REV and PAY) per billing item.

Filters:

  • Same filter logic as AR Aging Summary, applied to billing_item_detail and its joined billing_item

Computed Values:

  • detailBalance: billing_item_detail.billing_item_detail_total_amt - deductionsApplied(A/S) - cashApplied(A/S) for this specific detail
  • cashApplied: SUM(cash_receipt_application.cash_receipt_amt_applied) for this detail on worksheets with status = 'A' and current_item_ind = true
  • deductionTotal: SUM(billing_item_deduction.billing_item_deduction_amt WHERE billing_item_deduction_update_net_ind = true) for this detail
  • netAfterDeductions: billing_item_detail.billing_item_detail_gross_amt - deductionTotal
  • agingCurrent through aging90Plus: same bucket logic as Summary, but applied to detailBalance

Returns: Separate rows for each REV and PAY detail, each carrying detail-specific balance and aging bucket allocation, ordered by department_name, deal_name, billing_item_due_dt, billing_item_detail_type_cd.


2.7 Tax Support

2.7.1 UK Cumulative Gross for Party

Operation: getUkCumulativeGrossForParty

Input Parameters:

  • partyId: integer (required) — matched against billing_item.contracted_party_id OR billing_item.client_id
  • ukEntityIds: integer[] (required) — billing_item.uta_entity_id (IN list of UK UTA entity IDs)
  • taxYearStart: string/date (required) — billing_item.billing_item_due_dt lower bound
  • taxYearEnd: string/date (required) — billing_item.billing_item_due_dt upper bound

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_item_detailINNERbilling_itembilling_item_detail.billing_item_id = billing_item.billing_item_idAccess party, entity, and due-date fields for filtering

Filters:

  • billing_item_detail.billing_item_detail_type_cd = 'REV'
  • billing_item.current_item_ind = true
  • billing_item.contracted_party_id = :partyId OR billing_item.client_id = :partyId
  • billing_item.uta_entity_id IN (:ukEntityIds)
  • billing_item.billing_item_due_dt >= :taxYearStart
  • billing_item.billing_item_due_dt <= :taxYearEnd

Computed Values:

  • SUM(billing_item_detail.billing_item_detail_gross_amt) — cumulative REV gross for the party across UK entities within the tax year

Returns: A single numeric value representing the party's cumulative UK gross for the tax year, used to determine whether proactive FEU withholding should be applied when the total reaches or exceeds the £12,570 personal allowance threshold.


2.8 Dashboard Metrics

2.8.1 Past Due / Unconfirmed Billing Items

Operation: getPastDueNotConfirmedMetric

Input Parameters:

  • None

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_itemCount with date and status conditions

Filters:

  • billing_item.billing_item_due_dt < CURRENT_DATE
  • billing_item.billing_item_status_cd != 'C' — not Cancelled

Computed Values:

  • COUNT(*) — number of billing items past their due date that are not yet in Cancelled status

Returns: A single count value for dashboard display showing how many billing items are overdue and not yet resolved.


2.8.2 Revenue Billed Today

Operation: getRevenueBilledTodayTotal

Input Parameters:

  • None

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
billing_item_detailAggregate with type and posting-date conditions

Filters:

  • billing_item_detail.billing_item_detail_type_cd = 'REV'
  • billing_item_detail.posting_dt = CURRENT_DATE

Computed Values:

  • SUM(billing_item_detail.billing_item_detail_amt) — total REV commission amount posted today

Returns: A single monetary string for dashboard display showing total revenue billed today.


2.9 Revenue Item Queries

2.9.1 Revenue Item by ID

Operation: getRevenueItemById

Input Parameters:

  • id: integer (required) — revenue_items.revenue_item_id

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
revenue_itemsSingle-table select by primary key

Filters:

  • revenue_items.revenue_item_id = :id

Computed Values:

  • None

Returns: One revenue_items row or null.


2.9.2 Revenue Item by Sales Item Reference

Operation: getRevenueItemBySalesItemRef

Input Parameters:

  • salesItemRef: string (required) — revenue_items.sales_item_ref

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
revenue_itemsSingle-table select with reference and current-item filters

Filters:

  • revenue_items.sales_item_ref = :salesItemRef
  • revenue_items.current_item_ind = true

Computed Values:

  • None

Returns: The current revenue item matching the sales item reference, or null, used during sales item sync to find existing records.


2.9.3 Revenue Items by Client

Operation: getRevenueItemsByClientId

Input Parameters:

  • clientId: integer (required) — revenue_items.client_id

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
revenue_itemsLEFTuta_entityuta_entity.uta_entity_id = revenue_items.uta_entity_idEntity name
revenue_itemsLEFTdepartmentdepartment.department_id = revenue_items.department_idDepartment name
revenue_itemsLEFTdealdeal.deal_id = revenue_items.deal_idDeal name
revenue_itemsLEFTparty (as client)client.party_id = revenue_items.client_idClient display name
revenue_itemsLEFTparty (as buyer)buyer.party_id = revenue_items.buyer_idBuyer display name
revenue_itemsLEFTcode_master (as statusCm)revenue_items.revenue_item_status_cd = statusCm.code_master_cd AND statusCm.code_master_type = 'REVENUE_ITEM_STATUS_CD'Status description
revenue_itemsLEFTcode_master (as dateStatusCm)revenue_items.revenue_item_date_status_cd = dateStatusCm.code_master_cd AND dateStatusCm.code_master_type = 'REVENUE_ITEM_DATE_STATUS_CD'Date status description
revenue_itemsLEFTcode_master (as recStyleCm)revenue_items.revenue_item_rec_style_cd = recStyleCm.code_master_cd AND recStyleCm.code_master_type = 'REVENUE_ITEM_REC_STYLE_CD'Recognition style description

Filters:

  • revenue_items.client_id = :clientId

Computed Values:

  • cashCollected: correlated subquery — SUM(cash_receipt_application.cash_receipt_amt_applied) across all applications whose billing_item_detail belongs to a billing_item under this revenue item, joined through cash_receipt_applicationcash_receipt_worksheet (current, status IN ('A','S')) → billing_item_detailbilling_itemrevenue_items.revenue_item_id

Returns: Revenue items for the specified client, each enriched with entity, department, deal, party names, code descriptions, and a computed cashCollected total.


2.9.4 Revenue Items — List All

Operation: getAllRevenueItems

Input Parameters:

  • None

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
revenue_itemsLEFTuta_entityuta_entity.uta_entity_id = revenue_items.uta_entity_idEntity name
revenue_itemsLEFTdepartmentdepartment.department_id = revenue_items.department_idDepartment name
revenue_itemsLEFTdealdeal.deal_id = revenue_items.deal_idDeal name
revenue_itemsLEFTparty (as client)client.party_id = revenue_items.client_idClient display name
revenue_itemsLEFTparty (as buyer)buyer.party_id = revenue_items.buyer_idBuyer display name
revenue_itemsLEFTcode_master (as statusCm)revenue_items.revenue_item_status_cd = statusCm.code_master_cd AND statusCm.code_master_type = 'REVENUE_ITEM_STATUS_CD'Status description
revenue_itemsLEFTcode_master (as dateStatusCm)revenue_items.revenue_item_date_status_cd = dateStatusCm.code_master_cd AND dateStatusCm.code_master_type = 'REVENUE_ITEM_DATE_STATUS_CD'Date status description
revenue_itemsLEFTcode_master (as recStyleCm)revenue_items.revenue_item_rec_style_cd = recStyleCm.code_master_cd AND recStyleCm.code_master_type = 'REVENUE_ITEM_REC_STYLE_CD'Recognition style description

Filters:

  • None — returns all revenue items.

Computed Values:

  • cashCollected: same correlated subquery as 2.9.3

Returns: All revenue items with enrichment fields and cash-collected computation.


Operation: searchRevenueItems

Input Parameters:

  • searchTerm: string (optional) — case-insensitive pattern match on uta_entity.uta_entity_name, deal.deal_name, client.display_name, buyer.display_name, revenue_items.sales_item_ref, revenue_items.revenue_item_name
  • clientId: integer (optional) — revenue_items.client_id
  • revenueItemDateStatusCd: string (optional) — revenue_items.revenue_item_date_status_cd
  • currentItemInd: boolean (optional) — revenue_items.current_item_ind
  • limit: integer (optional) — row limit

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
revenue_itemsLEFTuta_entityuta_entity.uta_entity_id = revenue_items.uta_entity_idEntity name (also used in searchTerm filter)
revenue_itemsLEFTdepartmentdepartment.department_id = revenue_items.department_idDepartment name
revenue_itemsLEFTdealdeal.deal_id = revenue_items.deal_idDeal name (also used in searchTerm filter)
revenue_itemsLEFTparty (as client)client.party_id = revenue_items.client_idClient display name (also used in searchTerm filter)
revenue_itemsLEFTparty (as buyer)buyer.party_id = revenue_items.buyer_idBuyer display name (also used in searchTerm filter)
revenue_itemsLEFTcode_master (as statusCm)revenue_items.revenue_item_status_cd = statusCm.code_master_cd AND statusCm.code_master_type = 'REVENUE_ITEM_STATUS_CD'Status description
revenue_itemsLEFTcode_master (as dateStatusCm)revenue_items.revenue_item_date_status_cd = dateStatusCm.code_master_cd AND dateStatusCm.code_master_type = 'REVENUE_ITEM_DATE_STATUS_CD'Date status description
revenue_itemsLEFTcode_master (as recStyleCm)revenue_items.revenue_item_rec_style_cd = recStyleCm.code_master_cd AND recStyleCm.code_master_type = 'REVENUE_ITEM_REC_STYLE_CD'Recognition style description

Filters:

  • If searchTerm provided: case-insensitive pattern match across entity, deal, client, buyer, sales_item_ref, and revenue_item_name
  • If clientId provided: revenue_items.client_id = :clientId
  • If revenueItemDateStatusCd provided: revenue_items.revenue_item_date_status_cd = :revenueItemDateStatusCd
  • If currentItemInd provided: revenue_items.current_item_ind = :currentItemInd

Computed Values:

  • cashCollected: same correlated subquery as 2.9.3

Returns: Revenue items matching the search criteria, enriched with party/entity names, code descriptions, and cash-collected totals, ordered by revenue_items.revenue_item_id DESC.


2.10 Revenue Schedule Queries

2.10.1 Revenue Item Schedules by Item

Operation: getSchedulesByItemId

Input Parameters:

  • id: integer (required) — revenue_item_schedules.revenue_item_id

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
revenue_item_schedulesSingle-table select with parent-key filter

Filters:

  • revenue_item_schedules.revenue_item_id = :id

Computed Values:

  • None

Returns: All schedule rows for the specified revenue item, each representing a revenue recognition period with an amount and posting status.


2.10.2 Unposted Revenue Schedules Up to Date

Operation: getUnpostedSchedulesUpToDate

Input Parameters:

  • date: date (required) — upper bound for revenue_item_schedules.revenue_dt and revenue_item_schedules.created_dt

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
revenue_item_schedulesINNERrevenue_itemsrevenue_item_schedules.revenue_item_id = revenue_items.revenue_item_idAccess revenue_item_date_status_cd for confirmed-date filter

Filters:

  • revenue_item_schedules.revenue_item_posting_status_cd = 'U' — unposted
  • revenue_item_schedules.revenue_dt <= :date
  • revenue_item_schedules.created_dt <= :date
  • revenue_items.revenue_item_date_status_cd = 'C' — confirmed

Computed Values:

  • None

Returns: Each result pairs a revenue_item_schedules record with its parent revenue_items record, ordered by revenue_items.revenue_item_id ASC, revenue_item_schedules.revenue_dt ASC, revenue_item_schedules.revenue_item_schedule_id ASC, used by the revenue recognition posting job.


2.10.3 Posted Revenue Schedules Up to Date

Operation: getPostedSchedulesUpToDate

Input Parameters:

  • date: date (required) — upper bound for revenue_item_schedules.revenue_dt

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
revenue_item_schedulesSingle-table select with status and date filters

Filters:

  • revenue_item_schedules.revenue_item_posting_status_cd = 'P'
  • revenue_item_schedules.revenue_dt <= :date

Computed Values:

  • None

Returns: All posted schedule entries with a revenue date on or before the target date.


2.10.4 Past Start / Unconfirmed Revenue Items (Dashboard Metric)

Operation: getPastStartNotConfirmedMetric

Input Parameters:

  • None

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
revenue_itemsCount with date and status conditions

Filters:

  • revenue_items.revenue_item_start_dt < CURRENT_DATE
  • revenue_items.revenue_item_status_cd != 'C' — not Confirmed

Computed Values:

  • COUNT(*) — number of revenue items past their start date that are not yet confirmed

Returns: A single count value for dashboard display.


2.10.5 Revenue Recognized Today (Dashboard Metric)

Operation: getRevenueRecognizedTodayTotal

Input Parameters:

  • None

Tables & Joins:

Base TableJoinJoined TableConditionPurpose
revenue_item_schedulesAggregate with posting-date condition

Filters:

  • revenue_item_schedules.revenue_item_posting_dt = CURRENT_DATE

Computed Values:

  • SUM(revenue_item_schedules.revenue_amt) — total revenue recognized today

Returns: A single monetary string for dashboard display showing total revenue posted to GL today.


3. Calculations & Formulas

3.1 Balance Remaining (per detail)

text
detail_balance = billing_item_detail.billing_item_detail_total_amt
               - SUM(cash_receipt_application_deduction.deduction_amt_applied)   -- on qualifying worksheets
               - SUM(cash_receipt_application.cash_receipt_amt_applied)           -- on qualifying worksheets
  • Source: billing_item_detail.billing_item_detail_total_amt, cash_receipt_application_deduction.deduction_amt_applied, cash_receipt_application.cash_receipt_amt_applied
  • Qualifying worksheet filter: cash_receipt_worksheet.current_item_ind = true AND cash_receipt_worksheet.cash_receipt_worksheet_status_cd IN ('A', 'S')
  • Precision: decimal(15,2)

3.2 Balance Remaining (per billing item, combined)

text
balance = (revDetail.billing_item_detail_total_amt + payDetail.billing_item_detail_total_amt)
        - (rev_applied_deductions + pay_applied_deductions)
        - (rev_cash_applied + pay_cash_applied)
  • Source: REV and PAY aliases of billing_item_detail.billing_item_detail_total_amt; correlated subqueries for deductions and cash across both detail types
  • Precision: decimal(15,2)
  • Example: REV total $1,000.00 + PAY total $9,000.00 - applied deductions $500.00 - cash applied $2,000.00 = balance $7,500.00

3.3 Cash Applied (per detail)

text
cash_applied = SUM(cash_receipt_application.cash_receipt_amt_applied)
  • Source: cash_receipt_application.cash_receipt_amt_applied
  • Precision: decimal(15,2)
  • Tolerance: For display fields labeled "cash collected" (revCash, payCash), only status = 'A' (Approved) is used. For balance calculations, both 'A' and 'S' (Submitted) are included.

3.4 Deductions Billed (per detail)

text
deductions_billed = SUM(billing_item_deduction.billing_item_deduction_amt)
  • Source: billing_item_deduction.billing_item_deduction_amt
  • Precision: decimal(15,2)
  • Note: Includes all deductions regardless of billing_item_deduction_update_net_ind. Represents the total deduction amount recorded at billing time.

3.5 Deductions Applied (per detail)

text
deductions_applied = SUM(cash_receipt_application_deduction.deduction_amt_applied)
  • Source: cash_receipt_application_deduction.deduction_amt_applied
  • Precision: decimal(15,2)
  • Qualifying worksheet filter: cash_receipt_worksheet.current_item_ind = true AND cash_receipt_worksheet.cash_receipt_worksheet_status_cd IN ('A', 'S')

3.6 Deduction Balance (per detail)

text
deduction_balance = deductions_billed - deductions_applied
  • Source: billing_item_deduction.billing_item_deduction_amt, cash_receipt_application_deduction.deduction_amt_applied
  • Precision: decimal(15,2)

3.7 Total Applied Amount (per detail)

text
total_applied = cash_applied + deductions_applied
  • Source: cash_receipt_application.cash_receipt_amt_applied, cash_receipt_application_deduction.deduction_amt_applied
  • Precision: decimal(15,2)
  • Use: Used during rebilling to determine whether cash activity exists on a detail before migrating it.

3.8 Net After Deductions (AR Aging)

text
net_after_deductions = billing_item_detail_gross_amt
                     - SUM(billing_item_deduction.billing_item_deduction_amt
                           WHERE billing_item_deduction_update_net_ind = true)
  • Source: billing_item_detail.billing_item_detail_gross_amt, billing_item_deduction.billing_item_deduction_amt
  • Precision: decimal(15,2)
  • Note: Only deductions flagged as net-impacting (billing_item_deduction_update_net_ind = true) reduce the net amount. Used in the AR Aging report to show the effective billing amount after adjustments.

3.9 Aging Bucket Classification

text
days_overdue = CURRENT_DATE - billing_item.billing_item_due_dt

IF due_dt IS NULL OR due_dt >= CURRENT_DATE  -> bucket = Current
ELIF days_overdue BETWEEN 1 AND 30           -> bucket = 1-30
ELIF days_overdue BETWEEN 31 AND 60          -> bucket = 31-60
ELIF days_overdue BETWEEN 61 AND 90          -> bucket = 61-90
ELIF days_overdue > 90                       -> bucket = 90+
  • Source: billing_item.billing_item_due_dt, CURRENT_DATE
  • Note: The entire balance is placed into exactly one bucket — there is no proportional allocation.

3.10 Cash Collected on Revenue Item

text
cash_collected = SUM(cash_receipt_application.cash_receipt_amt_applied)
  • Source: cash_receipt_application.cash_receipt_amt_applied
  • Join path: cash_receipt_applicationcash_receipt_worksheet (current, status IN ('A','S')) → billing_item_detailbilling_itemrevenue_items.revenue_item_id
  • Precision: decimal(15,2)
  • Note: Computes total cash applied across all billing items linked to a revenue item.

3.11 REV/PAY Amount Split

text
REV:
  rev_gross_amt    = gross_amt
  rev_percent      = commission_perc
  rev_amt          = gross_amt * commission_perc
  rev_tax_amt      = 0 (unless tax deductions apply)
  rev_total_amt    = rev_amt + rev_tax_amt

PAY (standard collection style):
  pay_gross_amt    = gross_amt
  pay_percent      = 1 - commission_perc
  pay_amt          = gross_amt * pay_percent
  pay_tax_amt      = 0
  pay_total_amt    = pay_amt + pay_tax_amt

PAY (CLIENT collection style):
  All PAY amounts  = 0 (client collects directly; no payout flows through UTA)
  • Source: billing_item_detail.billing_item_detail_gross_amt, billing_item_detail.billing_item_detail_percent, billing_item_detail.billing_item_detail_amt, billing_item_detail.billing_item_detail_tax_amt, billing_item_detail.billing_item_detail_total_amt
  • Precision: amounts decimal(15,2), percent decimal(5,4)

4. Cross-References

DocumentRelationship
Billing Items Data ModelTable definitions, field types, constraints, and indexes for all tables covered by this domain.
Cash Receipts Queriescash_receipt_application and cash_receipt_application_deduction are consumed by flattened display and balance queries. Worksheet status and current_item_ind control which applications count toward balances.
Worksheets Data Modelcash_receipt_worksheet.current_item_ind and cash_receipt_worksheet_status_cd are the qualifying worksheet filters used throughout this domain's balance calculations.
Parties Data ModelClient, buyer, and collection party names are resolved via LEFT JOIN to party.
Deals, Sales Items & Payment Terms Data ModelDeal name and deal reference are resolved via LEFT JOIN to deal. UTA entity identification also drives the UK tax threshold query (section 2.7.1).
Tax Withholding QueriesThe UK cumulative gross query (section 2.7.1) feeds the proactive FEU withholding calculation. Results are consumed by the withholding tax service to determine whether the £12,570 personal allowance threshold has been reached.
Write-Offs Data Modelwrite_off_status_cd, write_off_dt, and write_off_packet_id on billing_item_detail are surfaced in display and aging queries. The includeWrittenOff filter controls visibility.
Accounting Data ModelBilling job queries (sections 2.5.1–2.5.3) and revenue recognition job queries (sections 2.10.2–2.10.3) identify records ready for GL posting and support posting date resets.

Confidential. For internal use only.