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:
- What is owed? — Billing items and their REV/PAY detail breakdown, enriched with party, deal, and entity context.
- What has been collected? — Cash applied and deductions applied against each billing item detail, computed from the cash application and worksheet tables.
- 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_itemwith 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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item | — | — | — | Single-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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item | — | — | — | Full 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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item | — | — | — | Single-table select with filters |
Filters:
billing_item.revenue_item_id=:revenueItemIdbilling_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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item_detail | — | — | — | Single-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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item_detail | — | — | — | Single-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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item_deduction | — | — | — | Single-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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item_deduction | — | — | — | Base 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:detailIdwherecash_receipt_application_deduction.billing_item_deduction_type_cdmatches the current row's type code, joined throughcash_receipt_applicationandcash_receipt_worksheet, filtered tocash_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 acrossbilling_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_refbillingItemId: integer (optional) —billing_item.billing_item_idbillingItemIds: integer[] (optional) —billing_item.billing_item_id(IN list)revenueItemId: integer (optional) —billing_item.revenue_item_idrevenueItemIds: integer[] (optional) —billing_item.revenue_item_id(IN list)billingItemStatusCd: string (optional) —billing_item.billing_item_status_cdcurrencyCd: string (optional) —billing_item.currency_cd(case-insensitive match)openItemOnly: boolean (optional) — when true,billing_item.open_item_ind = truecurrentItemOnly: boolean (optional) — when true,billing_item.current_item_ind = truerevenueItemDateStatusCd: string (optional) —revenue_items.revenue_item_date_status_cdhideZeroBillings: boolean (optional, default:true) — when true, excludes rows whererevDetail.billing_item_detail_gross_amt = 0includeWrittenOff: boolean (optional, default:false) — when false, excludes rows whererevDetail.write_off_status_cd = 'WRITTEN_OFF'clientId: integer (optional) —billing_item.client_idclientIds: integer[] (optional) —billing_item.client_id(IN list)buyerId: integer (optional) —billing_item.buyer_idbuyerIds: integer[] (optional) —billing_item.buyer_id(IN list)dealId: integer (optional) —billing_item.deal_iddealIds: integer[] (optional) —billing_item.deal_id(IN list)departmentId: integer (optional) —revenue_items.department_iddepartmentIds: integer[] (optional) —revenue_items.department_id(IN list)utaEntityId: integer (optional) —billing_item.uta_entity_idcollectionPartyIds: 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 limitoffset: integer (optional) — pagination offset
Tables & Joins:
| Base Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item | LEFT | billing_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_item | LEFT | billing_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_item | LEFT | party (as client) | client.party_id = billing_item.client_id | Client display name |
billing_item | LEFT | party (as buyer) | buyer.party_id = billing_item.buyer_id | Buyer display name |
billing_item | LEFT | uta_entity | uta_entity.uta_entity_id = billing_item.uta_entity_id | UTA entity name |
billing_item | LEFT | deal | deal.deal_id = billing_item.deal_id | Deal name and reference |
billing_item | LEFT | party (as collectionParty) | collectionParty.party_id = billing_item.collection_party_id | Collection party name |
billing_item | LEFT | revenue_items | revenue_items.revenue_item_id = billing_item.revenue_item_id | Revenue item name and sales item ref |
billing_item | LEFT | department | department.department_id = billing_item.department_id | Department 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 withstatus IN ('A','S')andcurrent_item_ind = truebillingItemTotalAmt: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 withstatus = 'A'andcurrent_item_ind = true(Approved only)payCash:SUM(cash_receipt_application.cash_receipt_amt_applied)for PAY detail on worksheets withstatus = 'A'andcurrent_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 statusIN ('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 detailrevAppliedDeductions:SUM(cash_receipt_application_deduction.deduction_amt_applied)for REV detail on qualifying worksheetsrevDeductionsBalance:revDeductions - revAppliedDeductionspayDeductions:SUM(billing_item_deduction.billing_item_deduction_amt)for PAY detailpayAppliedDeductions:SUM(cash_receipt_application_deduction.deduction_amt_applied)for PAY detail on qualifying worksheetspayDeductionsBalance:payDeductions - payAppliedDeductionsrevPercent: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=:clientIdbilling_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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
cash_receipt_application | INNER | cash_receipt_worksheet | cash_receipt_application.cash_receipt_worksheet_id = cash_receipt_worksheet.cash_receipt_worksheet_id | Filter by worksheet status and currency flag |
Filters:
cash_receipt_application.billing_item_detail_id=:detailIdcash_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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
cash_receipt_application | INNER | cash_receipt_worksheet | cash_receipt_application.cash_receipt_worksheet_id = cash_receipt_worksheet.cash_receipt_worksheet_id | Query 1: filter cash applications by worksheet status |
cash_receipt_application_deduction | INNER | cash_receipt_application | cash_receipt_application_deduction.cash_receipt_application_id = cash_receipt_application.cash_receipt_application_id | Query 2: link deduction to its application |
cash_receipt_application | INNER | cash_receipt_worksheet | cash_receipt_application.cash_receipt_worksheet_id = cash_receipt_worksheet.cash_receipt_worksheet_id | Query 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 forbilling_item.billing_item_due_dtandbilling_item_detail.created_dt
Tables & Joins:
| Base Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item_detail | INNER | billing_item | billing_item_detail.billing_item_id = billing_item.billing_item_id | Access header fields for due date and date-status filters |
billing_item | LEFT | revenue_items | billing_item.revenue_item_id = revenue_items.revenue_item_id | Retrieve sales_item_ref for GL posting reference |
Filters:
billing_item_detail.billing_item_detail_type_cd='REV'— only REV details are posted to GLbilling_item_detail.posting_status_cd='U'— unposted onlybilling_item.billing_item_due_dt_status_cd='C'— confirmed due datebilling_item.billing_item_due_dt<=:date— due on or before the target datebilling_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 forbilling_item_detail.posting_dt
Tables & Joins:
| Base Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item_detail | — | — | — | Direct 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'andposting_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 forbilling_item.billing_item_due_dt
Tables & Joins:
| Base Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item_detail | INNER | billing_item | billing_item_detail.billing_item_id = billing_item.billing_item_id | Step 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_idvalues; Step 2 updates those rows to setposting_status_cd = 'U'andposting_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_idbuyerId: integer (optional) —billing_item.buyer_iddealId: integer (optional) —billing_item.deal_iddepartmentId: integer (optional) —billing_item.department_idbillingItemId: integer (optional) —billing_item.billing_item_idcurrencyCd: string (optional) —billing_item.currency_cdcollectionStyleCd: string (optional) —billing_item.collection_style_cdopenItemOnly: boolean (optional) — when true,billing_item.open_item_ind = trueincludeWrittenOff: boolean (optional) — when false, excludesrevDetail.write_off_status_cd = 'WRITTEN_OFF'dueDateFrom: date (optional) —billing_item.billing_item_due_dt >= :dueDateFromdueDateTo: date (optional) —billing_item.billing_item_due_dt <= :dueDateTosearchTerm: string (optional) — case-insensitive pattern match onbilling_item.billing_item_name,client.display_name,buyer.display_name,deal.deal_name
Tables & Joins:
| Base Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item | LEFT | billing_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_item | LEFT | billing_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_item | LEFT | party (as client) | client.party_id = billing_item.client_id | Client display name |
billing_item | LEFT | party (as buyer) | buyer.party_id = billing_item.buyer_id | Buyer display name |
billing_item | LEFT | deal | deal.deal_id = billing_item.deal_id | Deal name |
billing_item | LEFT | department | department.department_id = billing_item.department_id | Department name |
Filters:
- All input parameters are applied when provided
- When
includeWrittenOffis 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 payscommissionPercent:revDetail.billing_item_detail_percentrevenueAmount:revDetail.billing_item_detail_total_amtcashCollected:SUM(cash_receipt_application.cash_receipt_amt_applied)for both REV and PAY details on worksheets withstatus IN ('A','S')andcurrent_item_ind = truedeductionTotal:SUM(billing_item_deduction.billing_item_deduction_amt WHERE billing_item_deduction_update_net_ind = true)for both REV and PAY detailsnetAfterDeductions:billingGrossAmt - deductionTotalhasDeductions:EXISTScheck for anybilling_item_deductionrows on either REV or PAY detailagingCurrent:totalBalancewhenbilling_item_due_dt IS NULL OR billing_item_due_dt >= CURRENT_DATE, else0aging1to30:totalBalancewhendaysOverdue BETWEEN 1 AND 30, else0aging31to60:totalBalancewhendaysOverdue BETWEEN 31 AND 60, else0aging61to90:totalBalancewhendaysOverdue BETWEEN 61 AND 90, else0aging90Plus:totalBalancewhendaysOverdue > 90, else0
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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item_detail | INNER | billing_item | billing_item_detail.billing_item_id = billing_item.billing_item_id | Access header fields; base table is detail not billing item |
billing_item | LEFT | party (as client) | client.party_id = billing_item.client_id | Client display name |
billing_item | LEFT | party (as buyer) | buyer.party_id = billing_item.buyer_id | Buyer display name |
billing_item | LEFT | deal | deal.deal_id = billing_item.deal_id | Deal name |
billing_item | LEFT | department | department.department_id = billing_item.department_id | Department 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_detailand its joinedbilling_item
Computed Values:
detailBalance:billing_item_detail.billing_item_detail_total_amt - deductionsApplied(A/S) - cashApplied(A/S)for this specific detailcashApplied:SUM(cash_receipt_application.cash_receipt_amt_applied)for this detail on worksheets withstatus = 'A'andcurrent_item_ind = truedeductionTotal:SUM(billing_item_deduction.billing_item_deduction_amt WHERE billing_item_deduction_update_net_ind = true)for this detailnetAfterDeductions:billing_item_detail.billing_item_detail_gross_amt - deductionTotalagingCurrentthroughaging90Plus: same bucket logic as Summary, but applied todetailBalance
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 againstbilling_item.contracted_party_idORbilling_item.client_idukEntityIds: integer[] (required) —billing_item.uta_entity_id(IN list of UK UTA entity IDs)taxYearStart: string/date (required) —billing_item.billing_item_due_dtlower boundtaxYearEnd: string/date (required) —billing_item.billing_item_due_dtupper bound
Tables & Joins:
| Base Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item_detail | INNER | billing_item | billing_item_detail.billing_item_id = billing_item.billing_item_id | Access party, entity, and due-date fields for filtering |
Filters:
billing_item_detail.billing_item_detail_type_cd='REV'billing_item.current_item_ind=truebilling_item.contracted_party_id = :partyId OR billing_item.client_id = :partyIdbilling_item.uta_entity_id IN (:ukEntityIds)billing_item.billing_item_due_dt>=:taxYearStartbilling_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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item | — | — | — | Count with date and status conditions |
Filters:
billing_item.billing_item_due_dt<CURRENT_DATEbilling_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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
billing_item_detail | — | — | — | Aggregate 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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
revenue_items | — | — | — | Single-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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
revenue_items | — | — | — | Single-table select with reference and current-item filters |
Filters:
revenue_items.sales_item_ref=:salesItemRefrevenue_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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
revenue_items | LEFT | uta_entity | uta_entity.uta_entity_id = revenue_items.uta_entity_id | Entity name |
revenue_items | LEFT | department | department.department_id = revenue_items.department_id | Department name |
revenue_items | LEFT | deal | deal.deal_id = revenue_items.deal_id | Deal name |
revenue_items | LEFT | party (as client) | client.party_id = revenue_items.client_id | Client display name |
revenue_items | LEFT | party (as buyer) | buyer.party_id = revenue_items.buyer_id | Buyer display name |
revenue_items | LEFT | code_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_items | LEFT | code_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_items | LEFT | code_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 whosebilling_item_detailbelongs to abilling_itemunder this revenue item, joined throughcash_receipt_application→cash_receipt_worksheet(current, statusIN ('A','S')) →billing_item_detail→billing_item→revenue_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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
revenue_items | LEFT | uta_entity | uta_entity.uta_entity_id = revenue_items.uta_entity_id | Entity name |
revenue_items | LEFT | department | department.department_id = revenue_items.department_id | Department name |
revenue_items | LEFT | deal | deal.deal_id = revenue_items.deal_id | Deal name |
revenue_items | LEFT | party (as client) | client.party_id = revenue_items.client_id | Client display name |
revenue_items | LEFT | party (as buyer) | buyer.party_id = revenue_items.buyer_id | Buyer display name |
revenue_items | LEFT | code_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_items | LEFT | code_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_items | LEFT | code_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.
2.9.5 Revenue Items — Search
Operation: searchRevenueItems
Input Parameters:
searchTerm: string (optional) — case-insensitive pattern match onuta_entity.uta_entity_name,deal.deal_name,client.display_name,buyer.display_name,revenue_items.sales_item_ref,revenue_items.revenue_item_nameclientId: integer (optional) —revenue_items.client_idrevenueItemDateStatusCd: string (optional) —revenue_items.revenue_item_date_status_cdcurrentItemInd: boolean (optional) —revenue_items.current_item_indlimit: integer (optional) — row limit
Tables & Joins:
| Base Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
revenue_items | LEFT | uta_entity | uta_entity.uta_entity_id = revenue_items.uta_entity_id | Entity name (also used in searchTerm filter) |
revenue_items | LEFT | department | department.department_id = revenue_items.department_id | Department name |
revenue_items | LEFT | deal | deal.deal_id = revenue_items.deal_id | Deal name (also used in searchTerm filter) |
revenue_items | LEFT | party (as client) | client.party_id = revenue_items.client_id | Client display name (also used in searchTerm filter) |
revenue_items | LEFT | party (as buyer) | buyer.party_id = revenue_items.buyer_id | Buyer display name (also used in searchTerm filter) |
revenue_items | LEFT | code_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_items | LEFT | code_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_items | LEFT | code_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
searchTermprovided: case-insensitive pattern match across entity, deal, client, buyer,sales_item_ref, andrevenue_item_name - If
clientIdprovided:revenue_items.client_id=:clientId - If
revenueItemDateStatusCdprovided:revenue_items.revenue_item_date_status_cd=:revenueItemDateStatusCd - If
currentItemIndprovided: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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
revenue_item_schedules | — | — | — | Single-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 forrevenue_item_schedules.revenue_dtandrevenue_item_schedules.created_dt
Tables & Joins:
| Base Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
revenue_item_schedules | INNER | revenue_items | revenue_item_schedules.revenue_item_id = revenue_items.revenue_item_id | Access revenue_item_date_status_cd for confirmed-date filter |
Filters:
revenue_item_schedules.revenue_item_posting_status_cd='U'— unpostedrevenue_item_schedules.revenue_dt<=:daterevenue_item_schedules.created_dt<=:daterevenue_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 forrevenue_item_schedules.revenue_dt
Tables & Joins:
| Base Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
revenue_item_schedules | — | — | — | Single-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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
revenue_items | — | — | — | Count with date and status conditions |
Filters:
revenue_items.revenue_item_start_dt<CURRENT_DATErevenue_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 Table | Join | Joined Table | Condition | Purpose |
|---|---|---|---|---|
revenue_item_schedules | — | — | — | Aggregate 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)
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 = trueANDcash_receipt_worksheet.cash_receipt_worksheet_status_cd IN ('A', 'S') - Precision:
decimal(15,2)
3.2 Balance Remaining (per billing item, combined)
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)
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), onlystatus = 'A'(Approved) is used. For balance calculations, both'A'and'S'(Submitted) are included.
3.4 Deductions Billed (per detail)
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)
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 = trueANDcash_receipt_worksheet.cash_receipt_worksheet_status_cd IN ('A', 'S')
3.6 Deduction Balance (per detail)
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)
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)
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
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
cash_collected = SUM(cash_receipt_application.cash_receipt_amt_applied)- Source:
cash_receipt_application.cash_receipt_amt_applied - Join path:
cash_receipt_application→cash_receipt_worksheet(current, statusIN ('A','S')) →billing_item_detail→billing_item→revenue_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
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), percentdecimal(5,4)
4. Cross-References
| Document | Relationship |
|---|---|
| Billing Items Data Model | Table definitions, field types, constraints, and indexes for all tables covered by this domain. |
| Cash Receipts Queries | cash_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 Model | cash_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 Model | Client, buyer, and collection party names are resolved via LEFT JOIN to party. |
| Deals, Sales Items & Payment Terms Data Model | Deal 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 Queries | The 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 Model | write_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 Model | Billing 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. |