Cash Matching Workflow

1. Executive Summary

Purpose

The cash matching workflow is the process by which a cash processor identifies which billing item receivables correspond to an incoming cash receipt split, annotates the split with reference tags (clients, deals, parties, departments), and selects the appropriate receivables to be carried forward into a worksheet for cash application. It sits between cash receipt ingestion (where money arrives) and worksheet application (where cash is formally applied to REV and PAY receivables). Cash matching answers the question: "This money arrived from a buyer — which deals and billing items does it pay for?"

Scope

Covered:

Viewing and filtering the queue of unprocessed cash receipt splits awaiting matching
Adding and removing reference tags (CLIENT_ID, BUYER_ID, CONTRACTED_PARTY_ID, DEAL_ID, DEPARTMENT_ID, SALES_ITEM_REF, PAYMENT_TERM_REF) to a split
Using references to filter the billing items grid and identify matching receivables
Configuring billing item display filters (open only, hide zero amounts, confirmed dates only, include written-off)
Selecting billing items from the filtered grid and carrying the selection into a worksheet
Accessing the split management panel to re-split or transfer funds before matching proceeds
Embedded receivable selection from within the worksheet detail page (Search Receivables dialog)

Not covered (documented separately):

Formal cash application (entering cash_receipt_amt_applied amounts per receivable) — see Worksheets Workflow
Worksheet lifecycle transitions (Apply, Settle, Approve, Return) — see Worksheets Workflow
Cash receipt creation, voiding, and adjustments — see Cash Receipts Workflow
Split submission and approval (agent-to-manager review) — see Cash Receipts Workflow
Settlement creation and payout processing — see Settlements Workflow

Key Objectives

Allow cash processors to quickly identify which open receivables correspond to a deposit, using reference tags as filters
Prevent mismatched cash applications by surfacing billing item balances, due dates, and tax status before cash is formally applied
Surface split-level tax warnings so users can assess withholding obligations before proceeding to a worksheet
Bridge the gap between unstructured bank remittance data and structured billing item records

2. Process Overview

mermaid

flowchart TD
    A[Cash Receipt Arrives\ncash_receipt created] --> B[Default Split Auto-Created\ncash_receipt_split sequence 1]
    B --> C{Split needs matching?}
    C -->|No active worksheet\nposting_status_cd = U| D[Appears in Matching Queue]
    C -->|Already submitted or approved\nworksheet exists| Z[Excluded from queue]
    D --> E[Processor selects split\nfrom left-panel list]
    E --> F[Add References to Split\ncash_receipt_reference rows created]
    F --> G[System filters billing items\nbased on references]
    G --> H{Items found?}
    H -->|Yes| I[Review matching items\ncheck balances, tax, due date]
    H -->|No| J[Adjust filters or\nadd more references]
    J --> F
    I --> K[Select billing items\ncheckbox multi-select]
    K --> L{Entry point?}
    L -->|Cash Matching standalone page| M[Proceed to Worksheet\nfor formal cash application]
    L -->|Search Receivables dialog\nin Worksheet| N[Items staged in worksheet\nReceivables table]
    M --> O[Worksheet Draft\ncash_receipt_worksheet status D]
    N --> O
    O --> P[Worksheet Workflow continues\nApply to Settle to Approve]

Walkthrough

Receipt split queued — When a cash_receipt arrives (manually entered or bank file–imported) and has no active worksheet in Submitted or Approved status, its default split appears in the matching queue. Only splits on unposted receipts (cash_receipt.posting_status_cd = 'U') are shown.
Processor selects a split — On the Cash Matching screen, the processor selects a split from the left-panel list. The right panel loads the split's details: deposit date, amount, notes, any attached files, and the source receipt's reference.
References added — The processor searches for parties, deals, revenue items, or billing items by name or reference code. Each search result can be pinned as a reference on the split (cash_receipt_reference). References are stored against the split for future use and drive the billing item filter.
Billing items filtered — As references are added, the system queries open billing items scoped to those clients, buyers, deals, departments, or payment term references. The grid updates automatically.
Filters adjusted — The processor can toggle filters: open items only, hide zero-amount billing items, confirmed due dates only, and include written-off items. Pagination loads 50 items per page with a "Load More" option.
Items selected — When using the Cash Matching page in standalone mode, the processor reviews the filtered billing items and identifies the correct receivables. When using the Search Receivables dialog from within a worksheet (selection mode), the processor checks billing items and clicks "Apply to Selected" to stage them in the worksheet.
Worksheet proceeds — The selected billing items are passed to the worksheet where the processor sets application amounts, then advances through Apply to Settle to Approve.

3. Business Rules

3.1 Queue Eligibility: Only Unposted Splits Without Active Submitted or Approved Worksheets

Business rule: A split appears in the matching queue only if its parent receipt is unposted (cash_receipt.posting_status_cd = 'U') and the split has no active worksheet (cash_receipt_worksheet.current_item_ind = true) in status Submitted ('S') or Approved ('A'). Splits that are already in a finalized or in-flight worksheet do not need matching.

Foundation reference: Cash Receipts Data Model — posting_status_cd

Workflow context: The exclusion is implemented via a NOT EXISTS subquery at queue load time. The status filter defaults to "Unmatched" (split_status_cd = 'N') on page load, so freshly arrived, never-matched splits are front and center.

3.2 References Are Informational and Not Foreign Key Constraints

Business rule: cash_receipt_reference rows store identifiers (party IDs, deal IDs, string references) as plain text. They are not enforced as foreign keys at the database level. Their sole purpose is to filter billing item searches and trigger split-level tax warning calculations.

Foundation reference: Cash Receipts Data Model — cash_receipt_reference

Workflow context: If a referenced entity (party, deal) is later deleted, the reference row becomes a dangling string. The application resolves references to display names at read time; if resolution fails, the raw ref_or_id value is shown as the label.

3.3 Tax Warning Is Set on the Split When a Party Reference Is Added

Business rule: When a CLIENT_ID or CONTRACTED_PARTY_ID reference is added to a split, the system evaluates whether withholding tax obligations apply based on the party's tax profile. If a tax scenario applies, cash_receipt_split.tax_warning_ind is set to true and tax_warning_json is populated with structured warning data.

Foundation reference: Cash Receipts Data Model — cash_receipt_split

IMPORTANT

Tax warnings on the split are early advisory information only. The authoritative tax calculation happens on the worksheet when billing item details are loaded. Split-level warnings use the reference to preview potential withholding; worksheet-level tax badges use the actual billing_item.client_id and billing_item.uta_entity_id.

3.4 Billing Item Filter Requires at Least One Reference

Business rule: The billing item grid returns no results if no references have been added to the split. At least one reference of any supported type must be present before the system executes the billing item query.

Foundation reference: Billing Items Queries — getBillingItemsDisplay

Workflow context: When the references list is empty, the Matching Items section shows a count of zero. An amber warning message is displayed when references are present but return no matching items.

3.5 Billing Item Balance Calculation

Business rule: The balance displayed for each billing item is billing_item_detail.billing_item_detail_total_amt minus the sum of cash_receipt_application.cash_receipt_amt_applied across all applications on worksheets that are current_item_ind = true and cash_receipt_worksheet_status_cd IN ('A', 'S'). Draft and returned worksheet applications are excluded from the balance calculation.

Foundation reference: Billing Items Data Model — calculated field rules

Workflow context: REV balance (revBalance) and PAY balance (payBalance) are shown as separate columns alongside the combined balance. This allows the processor to verify that the split amount is sufficient to cover both the commission and payout obligations.

3.6 Open Item Filter Default

Business rule: By default, the billing item grid shows only items where billing_item.open_item_ind = true and billing_item.current_item_ind = true. Items that are fully paid, written off to zero balance, or cancelled are hidden unless the user explicitly disables the "Open Only" filter.

Foundation reference: Billing Items Data Model — open_item_ind

3.7 Written-Off Items Are Hidden by Default

Business rule: Billing item details with write_off_status_cd = 'WRITTEN_OFF' are excluded from the matching grid by default. The processor can toggle "Include Written Off" to surface these items, which is useful when a recovery has been processed and cash needs to be re-applied.

Foundation reference: Billing Items Data Model — write_off_status_cd

3.8 Duplicate Reference Prevention

Business rule: A given combination of cash_receipt_split_id, type_cd, and ref_or_id is unique on the split. Attempting to add the same reference twice is a no-op — the system detects the duplicate and returns the existing reference ID without creating a second row.

Foundation reference: TODO: Document in foundation/procedures/cash-receipts.md

3.9 Confirmed Dates Filter Default

Business rule: By default, only billing items whose parent revenue_items.revenue_item_date_status_cd = 'C' (Confirmed) are shown. Items with unconfirmed dates represent deals that have not yet been finalized and may not be ready for cash application.

Foundation reference: Billing Items Data Model — revenue_item_date_status_cd

Workflow context: The processor can uncheck "Confirmed Dates Only" to see all billing items regardless of date confirmation status. This is commonly needed when a deal is in progress but cash has already arrived.

3.10 Pagination at 50 Items Per Page

Business rule: The billing items grid loads a maximum of 50 items per page. If more items match the current filters, a "Load More" button appears. Loading more appends results to the existing list rather than replacing it.

Foundation reference: TODO: Document in foundation/queries/billing-items.md

4. Data Access & Operations References

4.1 Queries Used

Operation	Foundation Doc	Purpose in This Workflow
`getCashReceiptSplitsForMatchingList`	TODO: Document in foundation/queries/cash-receipts.md	Loads the left-panel queue of unprocessed splits, filtering to unposted receipts with no active Submitted or Approved worksheet
`getCashReceiptDetails`	TODO: Document in foundation/queries/cash-receipts.md	Loads parent receipt detail (deposit date, total amount, currency, remittance info) for display in the right-panel header
`getCashReceiptReferences`	TODO: Document in foundation/queries/cash-receipts.md	Loads the current reference tags on the selected split, enriching party IDs and deal IDs with display names
`getFilteredBillingItems`	Billing Items Queries — getBillingItemsDisplay	Loads billing items filtered by the current references, open item flag, zero-amount flag, date status, and write-off status
`searchUniversal`	TODO: Document in foundation/queries/billing-items.md	Full-text search across `party`, `deal`, `revenue_items`, and `billing_item` tables to find reference candidates
`getDepartments`	TODO: Document in foundation/queries/billing-items.md	Loads the department list for the department reference selector

4.2 Procedures Used

Operation	Foundation Doc	Trigger in This Workflow
`addCashReceiptReference`	TODO: Document in foundation/procedures/cash-receipts.md	User selects a search result and pins it as a reference on the split
`removeCashReceiptReference`	TODO: Document in foundation/procedures/cash-receipts.md	User clicks the trash icon next to a reference in the Current References panel
`applyCashToBillingItems`	TODO: Document in foundation/procedures/worksheets.md	Used on the standalone Cash Matching page to get or create a worksheet and add initial applications (PoC artifact — see note below)

NOTE

PoC Artifact: The applyCashToBillingItems action on the standalone Cash Matching page directly creates applications from the matching screen by calling getOrCreateWorksheet and addApplication in sequence. In the full workflow, selected billing items from cash matching are passed to the worksheet where the processor enters application amounts explicitly before advancing to Apply. This direct-apply path may not survive into the production implementation.

5.1 Select Split from Matching Queue

Preconditions:

User is on the Cash Matching screen
At least one cash_receipt_split exists on an unposted receipt without an active Submitted or Approved worksheet

Procedure reference: TODO: Document in foundation/procedures/cash-receipts.md

Steps:

The left panel loads the queue of eligible splits sorted by deposit date ascending, then split sequence.
The user optionally applies the status filter tab (Unmatched, Partial, Applied, All) or secondary filters (date range, amount range).
The user clicks a split card. The right panel loads the split's detail view including receipt header, amount, deposit date, notes, attached files, and any existing references.

Postconditions:

The selected cash_receipt_split_id is active in the page state; the billing item grid is scoped to that split's existing references

UI trigger: Clicking a split card in the left panel. The selected card is visually highlighted. No separate button required.

5.2 Add Reference to Split

Preconditions:

A split is selected in the right panel
The split's parent receipt has cash_receipt.posting_status_cd = 'U'

Procedure reference: TODO: Document in foundation/procedures/cash-receipts.md

Steps:

User types at least two characters in the "Search Parties, Deals, Refs..." input. Results appear after a 300ms debounce.
For party results, the user selects the role: "Client" (CLIENT_ID), "Contr." (CONTRACTED_PARTY_ID), or "Buyer" (BUYER_ID). For deal, revenue item, or billing item results, the "+" button adds the reference directly with the corresponding type code.
For department references, user selects from the department dropdown combobox.
The reference is optimistically appended to the Current References list. A server call persists the cash_receipt_reference row and replaces the temporary ID with the real database ID.
The billing item grid refreshes automatically after a 300ms debounce.

Postconditions:

New cash_receipt_reference row exists with the selected type_cd and ref_or_id linked to cash_receipt_split_id
Billing item grid updated to include results matching the new reference

UI trigger: Typing in the search input and clicking a result action button (Client / Contr. / Buyer / +) or selecting from the department dropdown. Visible at all times when a split is selected.

5.3 Remove Reference from Split

Preconditions:

A split is selected
At least one reference exists in the Current References table

Procedure reference: TODO: Document in foundation/procedures/cash-receipts.md

Steps:

User clicks the trash icon in the rightmost column of a reference row.
The reference is immediately removed from the UI (optimistic delete).
A server call deletes the cash_receipt_reference row from the database.
The billing item grid refreshes automatically after the references debounce.

Postconditions:

cash_receipt_reference row deleted from the database
Billing item grid no longer filtered by that reference

UI trigger: Trash icon button in each reference row. Visible when the reference row is rendered. Always enabled.

5.4 Adjust Billing Item Display Filters

Preconditions:

A split is selected and at least one reference is present

Procedure reference: Billing Items Queries — getBillingItemsDisplay

Steps:

User toggles one or more filter checkboxes: "Open Only" (default on), "Show Zero" (default off — when on, zero-amount billing items are included), "Confirmed Dates Only" (default on), "Include Written Off" (default off).
Each toggle immediately triggers a fresh billing item query with the updated filter parameters.
The grid updates with the new result set, resetting to page 1.

Postconditions:

Billing item grid reflects the current filter combination; hasMore flag set if more than 50 items match

UI trigger: Checkbox controls in the Add Reference panel. Always visible when a split is selected.

5.5 Load More Billing Items

Preconditions:

Billing item grid has returned 50 items and hasMore = true

Procedure reference: Billing Items Queries — getBillingItemsDisplay

Steps:

User clicks the "Load More (N loaded)" button at the bottom of the grid.
The system fetches the next 50 items using the current filter parameters with an offset equal to the count already loaded.
New items are appended to the existing grid. The button updates its count or disappears if no more items remain.

Postconditions:

Up to 50 additional billing items appended to the current grid; hasMore updated

UI trigger: "Load More" button below the billing items grid. Visible only when hasMore = true. Shows a spinner while loading.

5.6 Select Billing Items for Worksheet (Selection Mode)

Preconditions:

The Cash Matching content is opened in selection mode (via the Search Receivables dialog on the worksheet detail page)
At least one reference is present and billing items are displayed
worksheetRemainingBalance is provided from the parent worksheet

Procedure reference: Worksheets Queries — getWorksheetByIdWithReceipt

Steps:

User checks one or more billing item rows using the checkbox column. The selection summary shows: Total Unapplied (worksheet remaining balance), Total Selected (sum of selected item balances), Total Remaining (unapplied minus selected), Total REV, Total PAY.
If Total Remaining becomes negative (selected exceeds remaining balance), the Total Remaining value is shown with a warning indicator.
User clicks "Apply to Selected (N)".
Selected billing items are passed back to the worksheet. The worksheet's pending receivables list is populated with these items, ready for amount entry.
The dialog closes.

Postconditions:

Selected BillingItemDisplay objects staged in the worksheet's pending rows state
No cash_receipt_application records created yet — those are created when the processor saves amounts on the worksheet

UI trigger: Checkbox column in each billing item row (selection mode only). "Apply to Selected (N)" button in the dialog footer. Button disabled when no items are selected.

5.7 Manage Splits (Re-Split or Transfer Funds)

Preconditions:

A split is selected in the left panel
The split's worksheet is in Draft status or the split has no worksheet

Procedure reference: TODO: Document in foundation/procedures/cash-receipts.md

Steps:

User clicks the "Manage Splits" button on the split card in the left panel.
The Split Management panel opens. The user can create additional splits, transfer funds between splits, or delete empty splits.
After changes are confirmed, the left panel refreshes to reflect the updated split list.

Postconditions:

cash_receipt_split records modified per the split management action; left panel list refreshed

UI trigger: "Manage Splits" button in each split card's footer. Visible on hover (or always when the split is selected). Opens the Split Management Sheet.

6. Permissions & Role-Based Access

Action	CASH_MANAGER	CASH_PROCESSOR	SETTLEMENT_APPROVER	IT
View matching queue	Yes	Yes	Yes	Yes
Add references to split	Yes	Yes	—	Yes
Remove references from split	Yes	Yes	—	Yes
View and filter billing items	Yes	Yes	Yes	Yes
Select billing items (selection mode, from worksheet)	Yes	Yes	—	Yes
Manage splits (re-split, transfer, delete)	Yes	Yes	—	Yes

Field-level restrictions:

The billing item grid is read-only in the Cash Matching context. Application amounts are entered on the worksheet detail page, not in cash matching.
Split notes are editable from the Cash Receipts workflow, not from the Cash Matching screen.
References on a split can only be added or removed if the parent receipt has cash_receipt.posting_status_cd = 'U'. Posted receipts restrict reference mutation.

NOTE

PoC Artifact: The PoC does not enforce role-based access checks on the Cash Matching page. All authenticated users can access the page and add references. Production implementation should restrict reference mutation to users with CASH_MANAGER or CASH_PROCESSOR roles.

7. Integration Points

7.1 Upstream

Source	Data Provided	Mechanism
Cash Receipts workflow	`cash_receipt` and `cash_receipt_split` records with deposit date, amount, currency, remittance info	FK lookup: `cash_receipt_split.cash_receipt_id` to `cash_receipt`
Bank Ingestion workflow	Bank transaction data auto-generates `cash_receipt` records; remittance info and bank reference ID flow through	`cash_receipt.bank_transaction_id` FK to `bank_transaction`
Deals and Billing Items workflow	`billing_item`, `billing_item_detail`, `revenue_items`, `deal`, `party` records that populate search results and the matching grid	FK lookups through `billing_item.deal_id`, `billing_item.client_id`, `billing_item.buyer_id`
Tax and Withholding service	Party tax profiles used to compute split-level tax warnings when `CLIENT_ID` or `CONTRACTED_PARTY_ID` references are added	`party_tax_info` looked up by `party_id` stored in `cash_receipt_reference.ref_or_id`

7.2 Downstream

Consumer	Data Consumed	Mechanism
Worksheets workflow	`cash_receipt_split_id` and selected `billing_item_detail` records passed into the worksheet for formal cash application	Split FK on worksheet: `cash_receipt_worksheet.cash_receipt_split_id`
Tax Calculation at worksheet level	`cash_receipt_reference` rows with `CLIENT_ID` used to seed the worksheet's receivable search with suggested party filters	References loaded at worksheet load time to pre-populate the receivable search filter state

7.3 External Integrations

No external integrations for this workflow. Cash matching is entirely internal — it reads from and writes to the internal database. Bank data arrives through the Bank Ingestion workflow before reaching the matching queue.

8. Functional Screen Requirements

8.1 Cash Matching Page

Route: /cash-matching

Data loading:

getCashReceiptSplitsForMatchingList — loads the initial queue of unprocessed splits (unposted receipts, no active Submitted or Approved worksheet)
getDepartments — pre-fetched once at page mount; passed down to avoid re-fetching per split selection

Left Panel: Cash Splits Queue

Displays the scrollable list of eligible cash receipt splits awaiting matching.

Filter controls (above the list):

Field / Column	Source	Editable?	Condition
Status filter tabs	Derived from `cash_receipt_split.split_status_cd` counts	Yes (tab click)	Always visible; tabs: Unmatched (`N`), Partial (`P`), Applied (`F` + `A`), All
Search input	Free-text filter on `cash_receipt.cash_receipt_ref` and `cash_receipt.cash_receipt_comment`	Yes	Always visible
Sort field selector	Sorts list by deposit date or split amount	Yes	Always visible
Sort direction toggle	Ascending or Descending	Yes	Always visible
Date filter	Preset: All Dates, Today, This Week, This Month	Yes	Always visible
Amount range filter	Min and Max popover; filters on `cash_receipt_split.split_amt`	Yes	Always visible; popover opens on button click

Split card fields:

Field / Column	Source	Editable?	Condition
Status badge	`cash_receipt_split.split_status_cd` mapped to label	No	Always visible
Split sequence number	`cash_receipt_split.split_sequence`	No	Always visible
Receipt reference	`cash_receipt.cash_receipt_ref`	No	Shown as "No Reference" when null
Split amount	`cash_receipt_split.split_amt` with `cash_receipt.currency_cd` prefix	No	Always visible
Deposit date	`cash_receipt.deposit_date`	No	Always visible
Total receipt amount	`cash_receipt.net_receipt_amt`	No	Always visible; shows parent receipt total for context
Notes preview	`cash_receipt_split.notes` (truncated with tooltip on hover)	No	Visible only when notes exist
Receipt comment	`cash_receipt.cash_receipt_comment` (truncated)	No	Visible only when comment exists
Attachment indicator	Presence of `cash_receipt_split.attachment_url`	No	Visible only when attachment exists; shows filename in tooltip
Manage Splits button	—	Yes (triggers action)	Visible on hover of any card; always visible on the selected card

Grid features:

Sortable columns: deposit date (default ascending), split amount
Filters: status tab, text search (debounced 300ms against receipt ref and comment), date preset, amount range
Row selection: single — clicking a card selects it and loads the right panel
Pagination: none — full list with client-side filtering and sorting

Conditional display:

The selected split card is highlighted with a distinct amber ring
"No splits found" empty state shown when filter combination returns zero results
Active secondary-filter indicator shows "N of M shown" and a "Clear filters" link when date or amount filter is active

Right Panel: Cash Matching Content

Displays the receipt and split header, reference management panels, and billing item grid for the selected split.

Data loading (triggered on split selection):

getCashReceiptDetails — loads parent receipt details (deposit date, total amount, remittance info, bank reference)
getCashReceiptReferences — loads existing reference tags for the split, enriching IDs to display names
getDepartments — if not already loaded from page mount

Shows split identity, status, notes, and the source receipt context.

Field / Column	Source	Editable?	Condition
Split number	`cash_receipt_split.split_sequence`	No	Always visible
Split status badge	`cash_receipt_split.split_status_cd` mapped to label	No	Visible when `split_status_cd` is present
Split notes	`cash_receipt_split.notes`	No	Visible when notes exist; displayed in an amber callout
Attached files	File records linked to the split (resolved via file service)	No (download link only)	Visible when file records exist
Source receipt ID	`cash_receipt.cash_receipt_id`	No	Always visible
Receipt reference	`cash_receipt.cash_receipt_ref`	No	Visible when not null
Receipt comment	`cash_receipt.cash_receipt_comment`	No	Visible when not null
Deposit date	`cash_receipt.deposit_date`	No	Always visible in amount card
Split amount	`cash_receipt_split.split_amt` with `cash_receipt.currency_cd` prefix	No	Always visible in amount card

Add Reference Panel

Allows the processor to find and pin reference tags that filter the billing items grid.

Field / Column	Source	Editable?	Condition
Search input	Free-text; searched against `party.display_name`, `party.full_name`, `deal.deal_name`, `deal.deal_reference`, `revenue_items.sales_item_ref`, `revenue_items.revenue_item_name`, `billing_item.payment_term_ref`, `billing_item.billing_item_name`	Yes	Always visible
Search results dropdown	Results from `searchUniversal`; grouped by result type (PARTY, DEAL, REVENUE_ITEM, BILLING_ITEM)	No (select actions only)	Visible after 2+ characters typed; hidden after selection or clear
Department combobox	`department.department_name` list	Yes	Always visible
Open Only checkbox	Filters `billing_item.open_item_ind = true`	Yes	Always visible; default checked
Show Zero checkbox	When checked, includes billing items with zero balances	Yes	Always visible; default unchecked
Confirmed Dates Only checkbox	Filters `revenue_items.revenue_item_date_status_cd = 'C'`	Yes	Always visible; default checked
Include Written Off checkbox	When checked, includes items with `billing_item_detail.write_off_status_cd = 'WRITTEN_OFF'`	Yes	Always visible; default unchecked

Conditional display:

Search results dropdown appears with a scrollable list when query length >= 2 characters
"No results found" message in dropdown when query returns empty
Clear button (X) inside search input appears when query is non-empty

Current References Panel

Shows the reference tags currently pinned to the split, which drive the billing item filter.

Field / Column	Source	Editable?	Condition
Type badge	`cash_receipt_reference.type_cd` formatted (underscores and suffix removed for display)	No	Always visible per row
Reference or Name	`cash_receipt_reference.entity_name` (resolved display name); raw `ref_or_id` shown below when they differ	No	Always visible per row
Delete button	—	Yes (triggers remove)	Always visible per row

Grid features:

Sortable columns: none
Filters: none
Row selection: none
Pagination: none

Conditional display:

"No references added" empty row shown when reference list is empty, with instructional text
Reference count badge shown in the panel header when at least one reference exists

Matching Items Grid

Shows billing items filtered by the current references and active filter settings.

Field / Column	Source	Editable?	Condition
Checkbox (select)	Row selection state	Yes (selection mode only)	Active in selection mode; hidden in standalone mode
Billing Item ID	`billing_item.billing_item_id`	No	Hidden by default
Sales Item Ref	`revenue_items.sales_item_ref`	No	Hidden by default; clicking the value adds it as a `SALES_ITEM_REF` reference
Payment Term Ref	`billing_item.payment_term_ref`	No	Always visible; clicking the value adds it as a `PAYMENT_TERM_REF` reference
Client	`party.display_name` for `billing_item.client_id`	No	Always visible
Deal Name	`deal.deal_name` for `billing_item.deal_id`	No	Always visible
Revenue Item Name	`revenue_items.revenue_item_name`	No	Always visible
Billing Item Name	`billing_item.billing_item_name`	No	Always visible
Due Date	`billing_item.billing_item_due_dt`	No	Always visible
Balance	Computed: REV balance + PAY balance	No	Always visible
Currency	`billing_item.currency_cd` description	No	Hidden by default
REV Balance	Computed: `billing_item_detail.billing_item_detail_total_amt` (REV) minus REV cash applied on approved worksheets	No	Always visible
PAY Balance	Computed: `billing_item_detail.billing_item_detail_total_amt` (PAY) minus PAY cash applied on approved worksheets	No	Always visible
Billing Gross Amount	`billing_item_detail.billing_item_detail_gross_amt` (REV detail)	No	Always visible
REV Amount	`billing_item_detail.billing_item_detail_amt` (REV)	No	Always visible
Billing Item Status	`billing_item.billing_item_status_cd` description	No	Always visible
Write-Off Status	`billing_item_detail.write_off_status_cd` (REV)	No	Always visible
Buyer	`party.display_name` for `billing_item.buyer_id`	No	Always visible
Collection Party	`party.display_name` for `billing_item.collection_party_id`	No	Always visible
Open Item	`billing_item.open_item_ind`	No	Always visible
Collection Style	`billing_item.collection_style_cd` description	No	Always visible
Commission %	`billing_item_detail.billing_item_detail_percent` (REV)	No	Always visible
Cash Applied	Sum of `cash_receipt_application.cash_receipt_amt_applied` across active approved worksheets	No	Always visible
Total Deductions	Sum of `billing_item_deduction.billing_item_deduction_amt` where `billing_item_deduction_update_net_ind = true`	No	Always visible
REV Net Amt	`billing_item_detail.billing_item_detail_amt` (REV)	No	Always visible
REV Tax Amt	`billing_item_detail.billing_item_detail_tax_amt` (REV)	No	Always visible
REV Total Amt	`billing_item_detail.billing_item_detail_total_amt` (REV)	No	Always visible
REV Cash Applied	Sum of REV `cash_receipt_application.cash_receipt_amt_applied`	No	Always visible
PAY Net Amt	`billing_item_detail.billing_item_detail_amt` (PAY)	No	Always visible
PAY Amount	`billing_item_detail.billing_item_detail_amt` (PAY)	No	Always visible
PAY Tax Amt	`billing_item_detail.billing_item_detail_tax_amt` (PAY)	No	Always visible
PAY Total Amt	`billing_item_detail.billing_item_detail_total_amt` (PAY)	No	Always visible
PAY Cash Applied	Sum of PAY `cash_receipt_application.cash_receipt_amt_applied`	No	Always visible
UTA Entity Name	`uta_entity.entity_name` for `billing_item.uta_entity_id`	No	Always visible
Created Date	`billing_item.created_dt`	No	Always visible

Grid features:

Sortable columns: all columns are sortable
Filters: driven by references and filter checkboxes in the Add Reference panel; debounced 300ms on reference changes
Row selection: checkbox multi-select, enabled in selection mode; disabled in standalone mode
Pagination: 50 items per page with "Load More" button that appends (does not replace) additional pages

Conditional display:

"Matching Items 0" badge shown when billing items list is empty
"No matching items found for current references" warning shown when references exist but return no results
"Load More (N loaded)" button shown when hasMore = true
Loading spinner shown on the Load More button while fetching additional pages
Selection summary bar (Total Unapplied, Total Selected, Total Remaining, Total REV, Total PAY) shown above the grid in selection mode only
Total Remaining shown with a warning indicator when negative (selected balance exceeds worksheet remaining balance)
"Apply to Selected (N)" and "Cancel" buttons shown in footer in selection mode; "Apply" button disabled when no items are selected
Billing items already added to the current worksheet are shown with a disabled (grayed) checkbox and cannot be re-selected

8.2 Search Receivables Dialog (Worksheet Entry Point)

Route: Overlay dialog within /worksheets/[id]

Data loading:

The dialog receives a worksheet object containing cashReceiptSplitId, cashReceiptId, receiptAmt, currencyCd, cashReceiptRef, depositDate, and cashReceiptComment from the parent worksheet page state
worksheetRemainingBalance passed from the worksheet's unapplied amount calculation
disabledBillingItemIds (list of billing_item_detail_id values already on the worksheet) passed to prevent duplicate selection
On mount, getCashReceiptReferences fetches existing references for the split
getDepartments fetches the department list if not already available

Field / Column	Source	Editable?	Condition
Title	Static text: "Search Receivables"	No	Always visible
Description	Static text instructing the user to search and select billing items	No	Always visible

Dialog Body

Renders the full Cash Matching Content in selection mode (isSelectionMode = true). All field inventory tables from Section 8.1 Right Panel: Cash Matching Content apply. In selection mode the following differences apply:

The receipt and split header region is suppressed; context is already visible in the parent worksheet
The checkbox column in the Matching Items grid is active and supports multi-selection
The selection summary bar shows the worksheetRemainingBalance passed from the worksheet
Billing items already on the worksheet are shown with a disabled checkbox

Grid features:

Sortable columns: all columns
Filters: controlled by references and filter checkboxes
Row selection: checkbox multi-select, enabled
Pagination: 50 items per page with Load More

Conditional display:

"Apply to Selected (N)" button in dialog footer enabled only when at least one item is selected
"Cancel" button always visible in dialog footer
Dialog is a full-screen overlay

9. Additional Diagrams

mermaid

sequenceDiagram
    participant P as Processor
    participant UI as Cash Matching UI
    participant DB as Database

    P->>UI: Select split from left panel
    UI->>DB: getCashReceiptDetails(cashReceiptId)
    UI->>DB: getCashReceiptReferences(cashReceiptSplitId)
    DB-->>UI: Receipt details and references loaded
    UI->>P: Display header + references panel

    P->>UI: Type search query (e.g., party name)
    UI->>DB: searchUniversal(query) [debounced 300ms]
    DB-->>UI: Parties, deals, revenue items, billing items
    UI->>P: Show results dropdown

    P->>UI: Click "Client" on party result
    UI->>DB: addCashReceiptReference(splitId, CLIENT_ID, partyId)
    DB-->>UI: Reference persisted, referenceId returned
    UI->>DB: getFilteredBillingItems(references, filters) [debounced 300ms]
    DB-->>UI: Billing items matching client
    UI->>P: Update Matching Items grid

    P->>UI: Check billing item rows (selection mode)
    P->>UI: Click "Apply to Selected"
    UI->>P: Selected BillingItemDisplay objects returned to worksheet
    Note over P,UI: Worksheet row staging in parent component<br/>No cash_receipt_application records created yet

10. Cross-References

Document	Relationship
Worksheets Data Model	Defines `cash_receipt_worksheet`, `cash_receipt_application`, and `cash_receipt_application_deduction` — the tables populated after billing items are selected and amounts are entered on the worksheet
Worksheets Queries	Specifies worksheet retrieval queries including `getWorksheetByIdWithReceipt`, which supplies `worksheetRemainingBalance` for selection mode
Billing Items Data Model	Defines `billing_item`, `billing_item_detail`, `billing_item_deduction` — the receivable tables searched and displayed in cash matching
Billing Items Queries	Specifies `getBillingItemsDisplay` — the flattened query that powers the Matching Items grid
Cash Receipts Data Model	Defines `cash_receipt`, `cash_receipt_split`, `cash_receipt_reference`, `cash_receipt_adjustment` — the upstream structures that the matching queue reads from
Cash Receipts Workflow	Upstream: receipt creation, split management, agent submission, and cash manager approval all precede cash matching
Worksheets Workflow	Downstream: once billing items are selected via cash matching, they are applied, settled, and approved through the worksheet lifecycle

11. Gherkin Scenarios

gherkin

Feature: Cash Matching - Split Queue and Reference Management

  Scenario: Processor matches an unposted receipt split to a client's receivables
    Given a cash_receipt with posting_status_cd = 'U' and deposit_date = '2026-02-15' exists with cash_receipt_id = 1001
    And a cash_receipt_split with split_amt = 50000.00 and split_status_cd = 'N' and split_sequence = 1 exists with cash_receipt_split_id = 2001
    And no cash_receipt_worksheet with current_item_ind = true and cash_receipt_worksheet_status_cd IN ('S', 'A') exists for split 2001
    And a party with party_id = 301 and display_name = 'Kendrick Maxwell' exists
    And billing_item records exist for client_id = 301 with open_item_ind = true and current_item_ind = true
    When the processor navigates to the Cash Matching screen
    Then cash_receipt_split 2001 appears in the left-panel queue with status label "Unmatched"
    When the processor selects split 2001
    Then the right panel displays deposit date "FEB-15-2026" and amount "USD 50,000.00"
    When the processor types "Kendrick" in the search input
    And selects "Client" for party 301 in the search results dropdown
    Then a cash_receipt_reference row exists with cash_receipt_split_id = 2001, type_cd = 'CLIENT_ID', ref_or_id = '301'
    And the Matching Items grid displays billing items for client_id = 301

  Scenario: Reference filter returns no results and processor adds a different reference type
    Given a cash_receipt_split with split_amt = 25000.00 and cash_receipt_split_id = 2002 exists on an unposted receipt
    And a cash_receipt_reference with type_cd = 'BUYER_ID' and ref_or_id = '999' exists for split 2002
    And no billing_item records exist with buyer_id = 999 and open_item_ind = true
    When the processor views the Cash Matching content for split 2002
    Then the Matching Items grid shows 0 items
    And the message "No matching items found for current references" is visible
    When the processor removes the BUYER_ID reference for ref_or_id = '999'
    And adds a DEAL_ID reference for deal_id = 500
    And billing_item records exist for deal_id = 500 with open_item_ind = true
    Then the Matching Items grid updates to show billing items for deal_id = 500

  Scenario: Processor enables "Include Written Off" to find a previously written-off receivable
    Given a billing_item_detail with billing_item_detail_id = 8001 and write_off_status_cd = 'WRITTEN_OFF' exists for client_id = 301
    And a cash_receipt_reference with type_cd = 'CLIENT_ID' and ref_or_id = '301' exists for cash_receipt_split_id = 2003
    When the processor views the Cash Matching content for split 2003 with default filters (includeWrittenOff = false)
    Then billing_item_detail 8001 is not shown in the Matching Items grid
    When the processor checks the "Include Written Off" checkbox
    Then billing_item_detail 8001 appears in the Matching Items grid
    And the Write-Off Status column for that row shows 'WRITTEN_OFF'

  Scenario: Processor disables "Open Only" to find a fully-paid billing item
    Given a billing_item with billing_item_id = 7001 and open_item_ind = false exists for client_id = 301
    And a cash_receipt_reference with type_cd = 'CLIENT_ID' and ref_or_id = '301' exists for cash_receipt_split_id = 2004
    When the processor views the Cash Matching content for split 2004 with default filters (showOpenOnly = true)
    Then billing_item 7001 is not shown in the Matching Items grid
    When the processor unchecks the "Open Only" checkbox
    Then billing_item 7001 appears in the Matching Items grid
    And the Balance column for that row shows 0.00

  Scenario: Processor selects billing items in Search Receivables dialog and stages them in the worksheet
    Given a cash_receipt_worksheet with cash_receipt_worksheet_id = 3001 and cash_receipt_worksheet_status_cd = 'D' exists for cash_receipt_split_id = 2005
    And the worksheet unapplied_amount = 75000.00
    And a cash_receipt_reference with type_cd = 'CLIENT_ID' and ref_or_id = '301' already exists for split 2005
    And billing items for client_id = 301 are displayed with combined balance = 50000.00, revBalance = 15000.00, payBalance = 35000.00
    When the processor opens the Search Receivables dialog from worksheet 3001
    And checks 2 billing item rows with combined balance = 50000.00
    Then the selection summary shows Total Unapplied = 75,000.00, Total Selected = 50,000.00, Total Remaining = 25,000.00, Total Rev = 15,000.00, Total Pay = 35,000.00
    When the processor clicks "Apply to Selected (2)"
    Then the 2 selected BillingItemDisplay objects are staged as pending rows in the worksheet receivables table
    And the Search Receivables dialog closes
    And no cash_receipt_application rows have been created yet

  Scenario: Selecting billing items that exceed the worksheet remaining balance shows a warning
    Given a cash_receipt_worksheet with unapplied_amount = 10000.00 exists for cash_receipt_split_id = 2006
    And billing items with total combined balance = 15000.00 are displayed in the Search Receivables dialog
    When the processor selects all displayed billing items (totalSelected = 15000.00)
    Then the Total Remaining in the selection summary shows -5,000.00 with a warning indicator

  Scenario: Duplicate reference addition is silently ignored
    Given a cash_receipt_reference with type_cd = 'DEAL_ID' and ref_or_id = '500' already exists for cash_receipt_split_id = 2007
    When the processor attempts to add another DEAL_ID reference for deal_id = 500 via the search input
    Then no new cash_receipt_reference row is created for split 2007
    And the Current References panel still shows exactly one DEAL_ID reference with ref_or_id = '500'

  Scenario: Split with an active Approved worksheet does not appear in the matching queue
    Given a cash_receipt with posting_status_cd = 'U' exists with cash_receipt_id = 1002
    And a cash_receipt_split with cash_receipt_split_id = 2008 belongs to receipt 1002
    And a cash_receipt_worksheet with current_item_ind = true and cash_receipt_worksheet_status_cd = 'A' exists for split 2008
    When the processor navigates to the Cash Matching screen
    Then cash_receipt_split 2008 does not appear in the left-panel queue under any status filter tab

  Scenario: Processor uses department reference to narrow billing items to a specific UTA department
    Given a cash_receipt_split with cash_receipt_split_id = 2009 exists on an unposted receipt
    And a department with department_id = 45 and department_name = 'Music' exists
    And billing_item records for department_id = 45 with open_item_ind = true exist
    When the processor selects split 2009 in the Cash Matching screen
    And selects "Music" from the department dropdown
    Then a cash_receipt_reference row exists with cash_receipt_split_id = 2009, type_cd = 'DEPARTMENT_ID', ref_or_id = '45'
    And the Matching Items grid displays only billing items with department_id = 45

Sample Deals

Touring Deal

Endorsement Deal

Sports Endo Deal

Cash Matching Workflow ​

1. Executive Summary ​

Purpose ​

Scope ​

Key Objectives ​

2. Process Overview ​

Walkthrough ​

3. Business Rules ​

3.1 Queue Eligibility: Only Unposted Splits Without Active Submitted or Approved Worksheets ​

3.2 References Are Informational and Not Foreign Key Constraints ​

3.3 Tax Warning Is Set on the Split When a Party Reference Is Added ​

3.4 Billing Item Filter Requires at Least One Reference ​

3.5 Billing Item Balance Calculation ​

3.6 Open Item Filter Default ​

3.7 Written-Off Items Are Hidden by Default ​

3.8 Duplicate Reference Prevention ​

3.9 Confirmed Dates Filter Default ​

3.10 Pagination at 50 Items Per Page ​

4. Data Access & Operations References ​

4.1 Queries Used ​

4.2 Procedures Used ​

5. Key User Actions ​

5.1 Select Split from Matching Queue ​

5.2 Add Reference to Split ​

5.3 Remove Reference from Split ​

5.4 Adjust Billing Item Display Filters ​

5.5 Load More Billing Items ​

5.6 Select Billing Items for Worksheet (Selection Mode) ​

5.7 Manage Splits (Re-Split or Transfer Funds) ​

6. Permissions & Role-Based Access ​

7. Integration Points ​

7.1 Upstream ​

7.2 Downstream ​

7.3 External Integrations ​

8. Functional Screen Requirements ​

8.1 Cash Matching Page ​

Left Panel: Cash Splits Queue ​

Right Panel: Cash Matching Content ​

Header Region ​

Add Reference Panel ​

Current References Panel ​

Matching Items Grid ​

8.2 Search Receivables Dialog (Worksheet Entry Point) ​

Dialog Header Region ​

Dialog Body ​

9. Additional Diagrams ​

10. Cross-References ​

11. Gherkin Scenarios ​

Cash Matching Workflow

1. Executive Summary

Purpose

Scope

Key Objectives

2. Process Overview

Walkthrough

3. Business Rules

3.1 Queue Eligibility: Only Unposted Splits Without Active Submitted or Approved Worksheets

3.2 References Are Informational and Not Foreign Key Constraints

3.3 Tax Warning Is Set on the Split When a Party Reference Is Added

3.4 Billing Item Filter Requires at Least One Reference

3.5 Billing Item Balance Calculation

3.6 Open Item Filter Default

3.7 Written-Off Items Are Hidden by Default

3.8 Duplicate Reference Prevention

3.9 Confirmed Dates Filter Default

3.10 Pagination at 50 Items Per Page

4. Data Access & Operations References

4.1 Queries Used

4.2 Procedures Used

5. Key User Actions

5.1 Select Split from Matching Queue

5.2 Add Reference to Split

5.3 Remove Reference from Split

5.4 Adjust Billing Item Display Filters

5.5 Load More Billing Items

5.6 Select Billing Items for Worksheet (Selection Mode)

5.7 Manage Splits (Re-Split or Transfer Funds)

6. Permissions & Role-Based Access

7. Integration Points

7.1 Upstream

7.2 Downstream

7.3 External Integrations

8. Functional Screen Requirements

8.1 Cash Matching Page

Left Panel: Cash Splits Queue

Right Panel: Cash Matching Content

Header Region

Add Reference Panel

Current References Panel

Matching Items Grid

8.2 Search Receivables Dialog (Worksheet Entry Point)

Dialog Header Region

Dialog Body

9. Additional Diagrams

10. Cross-References

11. Gherkin Scenarios