Settlements Workflow

1. Executive Summary

Purpose

The Settlements workflow determines how the PAY portion of applied cash is divided among the client's party — the artist, manager, lawyer, business manager, and any other deal participants — and transmits those funds to the bank. Settlements are created after a worksheet has been applied (status 'P'): the Cash Processor selects PAY receivable rows, opens the settlement form, allocates the PAY amount among deal parties according to their commission terms, and saves. The Settlement Approver then approves the worksheet, which materializes outbound payment items ready for bank transmission. This workflow is the final stage of the cash-application lifecycle that sends money out of the building.

Scope

Covered:

• Creating, editing, and deleting participant_settlement records from an Applied worksheet
• Allocating the PAY amount among deal parties (participant_settlement_item)
• Auto-creation of cash_receipt_payout records that bridge settlements to the payment layer
• Worksheet lifecycle transitions that drive settlement status changes (Applied → Settled → Approved → Returned)
• Materialization of payment_item records at worksheet approval
• Passthrough and VAT pass-through payout creation (direct payments that bypass the settlement distribution process)
• Lock and reversal rules governing what can and cannot be undone after a payment has been sent

Not covered (documented separately):

• Worksheet creation, cash application (REV and PAY entries), and the Apply transition — see Worksheets Workflow
• Outbound payment processing, bank transmission, and status polling — see Payments Workflow
• Worksheet return (three-document model, reversal worksheet, replacement draft) — see Worksheets Workflow

Key Objectives

• Correctly divide the PAY portion of each applied receivable among the client's deal parties according to commission terms.
• Ensure settlement totals balance against PAY applied before the worksheet can be settled.
• Prevent modification of settlements whose payments have already been transmitted to the bank.
• Produce one payment_item per payee at worksheet approval so the Payments workflow can transmit funds to the bank.
• Provide an immutable audit trail: locked items are preserved as read-only context on replacement drafts when a worksheet is returned.

---

2. Process Overview

flowchart TD
    A[Worksheet reaches Applied status] --> B[Cash Processor selects PAY receivable rows]
    B --> C[Cash Processor opens Create Settlement form]
    C --> D[System pre-populates deal parties and commission defaults]
    D --> E[User adjusts commission amounts / parties]
    E --> F{Settlement total = PAY applied?}
    F -->|No| G[Validation error shown - user corrects amounts]
    G --> E
    F -->|Yes| H[Settlement saved — participant_settlement status = D]
    H --> I[Payouts auto-created — cash_receipt_payout type S]
    I --> J{All PAY applications have settlements?}
    J -->|No| K[Settle button disabled — user creates remaining settlements]
    K --> B
    J -->|Yes| L[Cash Processor clicks Settle]
    L --> M[Worksheet status → Settled T]
    M --> N[Settlement statuses → Settled T]
    N --> O[Settlement Approver reviews and clicks Approve]
    O --> P[Worksheet status → Approved A]
    P --> Q[Settlement statuses → Approved A]
    Q --> R[payment_item records created from payouts]
    R --> S{Payment date in future or do-not-send?}
    S -->|Yes| T[payment_item status = WAITING]
    S -->|No| U[payment_item status = PENDING]
    T --> V[Payments workflow picks up PENDING items]
    U --> V
    V --> W{Payment sent to bank?}
    W -->|Yes - SENT or later| X[Settlement and PAY application locked]
    W -->|No - PENDING/WAITING/FAILED| Y[Remains reversible]

Walkthrough

1. Select PAY receivables — While the worksheet is in Applied status, the Cash Processor selects one or more rows from the Receivables table. The rows must be PAY-type applications belonging to the same deal. The "Create Settlement" button becomes enabled when eligible PAY rows are selected.

2. Pre-populate settlement defaults — When the user opens the settlement form, the system calls computeSettlementDefaults to load deal party commission percentages, PAY applied amount, deduction amounts, and bank account information from the deal's party roster.

3. Enter commission allocations — The user reviews the pre-populated party list and commission amounts. For each party, the user can choose between a percentage-based or flat-amount commission. The calc_level_cd field controls whether commission is calculated on the gross PAY or the net PAY (after deductions). The user can also set a requested payment date and mark a payee as "do not send."

4. Validate and save — On save, the system validates that the sum of commission amounts equals the PAY applied amount (tolerance: 0.01). If validation passes, a participant_settlement header and one participant_settlement_item per non-zero payee are created with participant_settlement_status_cd = 'D'. The linked cash_receipt_application records are updated with participant_settlement_id.

5. Auto-create payouts — Immediately after saving the settlement, cash_receipt_payout records of type 'S' are created for each non-zero settlement item. These bridge the settlement to the payment layer. This step is idempotent.

6. Settle the worksheet — Once all PAY applications have settlements, the Settle button is enabled. The Cash Processor clicks Settle, transitioning the worksheet to Settled ('T') and all linked settlements to Settled status ('T').

7. Approve the worksheet — The Settlement Approver reviews the settled worksheet and clicks Approve. This transitions the worksheet to Approved ('A'), sets all settlements to Approved ('A'), and creates payment_item records from the cash_receipt_payout entries.

8. Payment items enter transmission queue — Each new payment item starts as WAITING (future-dated or do-not-send) or PENDING (ready for immediate processing). The Payments workflow picks up PENDING items for bank transmission.

9. Locking on transmission — Once a payment item reaches SENT status, the entire settlement, its items, and the associated PAY and REV applications are locked. Locked items cannot be reversed, modified, or deleted.

---

3. Business Rules

3.1 Settlement Only Divides PAY

Business rule: Settlements divide only the PAY portion of applied cash. REV applications (UTA's revenue) are never part of a settlement and cannot be selected for settlement creation.

Foundation reference: Settlements Data Model — Business Validation

Workflow context: On the Receivables table, only rows for PAY-type billing item details (billing_item_detail.billing_item_detail_type_cd = 'PAY') activate the "Create Settlement" button when selected. Selecting REV rows alone does not enable the button.

---

3.2 Settlement Total Must Balance Against PAY Applied

Business rule: The sum of all participant_settlement_item.participant_settlement_commission_amt values in a settlement must equal the total PAY applied on the worksheet, within a tolerance of 0.01.

Foundation reference: Settlements Queries — Validate Settlement Total

Workflow context: The settlement form shows the PAY applied amount as a reference. If the user saves with a total that does not balance, an error message states the settlement total and the expected PAY applied amount. The user must correct commission amounts before saving.

---

3.3 All PAY Applications Must Have Settlements Before Settling

Business rule: A worksheet cannot transition from Applied ('P') to Settled ('T') until every PAY application on the worksheet has a participant_settlement_id assigned.

Foundation reference: Worksheets Data Model — Settle Transition Preconditions

Workflow context: The Settle button is disabled with tooltip text "Create settlements for all PAY applications before settling" when any PAY application has cash_receipt_application.participant_settlement_id = NULL.

---

3.4 Same-Deal Receivables Only

Business rule: All receivables selected for a single settlement must belong to the same deal (same billing_item.deal_id). A settlement cannot span multiple deals.

Foundation reference: Settlements Data Model — Business Validation

---

3.5 Settlement Creation Requires Applied Worksheet

Business rule: Settlements can only be created when the parent worksheet is in Applied ('P') status. Creating or editing a settlement on a Draft or Approved worksheet is not permitted.

Foundation reference: Settlements Data Model — Business Validation

Workflow context: The "Create Settlement" button is only visible when cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'P'.

---

3.6 Commission Calculation: DNI vs. IGN

Business rule: Settlement commission can be calculated on the net PAY amount (after deductions, calc_level_cd = 'DNI') or on the gross PAY amount (before deductions, calc_level_cd = 'IGN'). The default is DNI.

Foundation reference: Settlements Data Model — CALC_LEVEL_CD Code Master

Workflow context: Each settlement item row in the form shows a "Calculation Level" selector (DNI or IGN). When the user changes this value, the displayed commission amount recalculates using the appropriate base.

---

3.7 Settlement-Level Locking

Business rule: If any single participant_settlement_item within a settlement has a linked payment_item in a locked status (PROCESSING, SENT, ACKNOWLEDGED, or PAID), then the entire settlement and all its items are locked. A single locked payment locks the whole settlement.

Foundation reference: Settlements Data Model — Business Validation and Settlements Queries — Lock Status Determination

Workflow context: Locked settlement items display a lock icon on the Receivables table row. The entire settlement form becomes read-only. The Delete button is removed.

---

3.8 Cannot Delete Settlement with Locked Payments

Business rule: A settlement with one or more locked payment items (PROCESSING, SENT, ACKNOWLEDGED, or PAID) cannot be deleted. The system blocks deletion and surfaces an error.

Foundation reference: Settlements Procedures — Delete Settlement

Workflow context: When the user attempts to delete a locked settlement, an error toast displays: "Cannot delete settlement with locked payment items. One or more payments have been sent to the bank."

---

3.9 Payment Items Created at Approval, Not at Settlement Save

Business rule: payment_item records are not created when a settlement is saved. They are created at worksheet approval (Settled → Approved transition) from the cash_receipt_payout records.

Foundation reference: Settlements Data Model — Payment Item Creation Trigger

---

3.10 Initial Payment Status Determined by Payment Date and Do-Not-Send Flag

Business rule: A newly created payment item starts as WAITING if its payment_date is in the future or do_not_send_ind = true. Otherwise, it starts as PENDING and is immediately eligible for bank transmission.

Foundation reference: Settlements Queries — Payment Item Initial Status Determination

---

3.11 GL Posting Happens Only After Bank Confirmation

Business rule: Payment items are created with posting_status_cd = 'U' (Unposted). The GL posting process only picks up payment items after the bank confirms receipt (ACKNOWLEDGED or PAID). Cancelled payment items are set to posting_status_cd = 'X' (Skipped) — never to 'U' — so the GL posting job never processes them.

Foundation reference: Settlements Data Model — GL Posting Status

WARNING

Never set posting_status_cd = 'U' on a cancelled or voided payment item. Doing so would cause the GL posting job to attempt to post an entry for a payment that was never sent, creating a GL imbalance.

---

3.12 Override Tracking

Business rule: When a user manually changes commission percentages or amounts from the deal-party defaults, participant_settlement.participant_settlement_overrided_ind is set to true. This flag signals that the settlement does not reflect the standard deal terms.

Foundation reference: Settlements Data Model — participant_settlement

---

4. Data Access & Operations References

4.1 Queries Used

Operation	Foundation Doc	Purpose in This Workflow
getSettlementDefaults	Settlement Defaults	Pre-populates the settlement form with deal party commission defaults, PAY totals, and deduction amounts when the user opens Create Settlement
validateSettlementTotal	Validate Settlement Total	Verifies commission totals balance against PAY applied before saving
getSettlement	Get Settlement by ID	Loads an existing settlement for display and edit, including per-item lock status
getSettlementEnriched	Get Settlement Enriched	Loads settlement with party names, roles, and bank account details for the settlement form
getSettlementByApplicationIds	Get Settlement by Application IDs	Looks up the settlement linked to selected receivable applications (for edit flow)
getSettlementsByWorksheetId	Get Settlements by Worksheet ID	Loads all settlements on a worksheet for the Receivables table settlement badge display
checkLockedPaymentsForDeletion	Check Locked Payments Before Deletion	Guards settlement deletion — blocks if any linked payment items are locked
getPaymentPayouts	Get Payment Payouts for Worksheet	Loads all payout records for the Payments tab on the worksheet
checkExistingVatPayout	Check Existing VAT Pass-Through Payout	Idempotency check before creating a VAT pass-through payout

4.2 Procedures Used

Operation	Foundation Doc	Trigger in This Workflow
computeSettlementDefaults	Compute Settlement Defaults	User opens the Create Settlement form with PAY rows selected
createSettlement	Create Settlement	User saves a new settlement from the settlement form
updateSettlement	Update Settlement	User edits and saves an existing settlement
deleteSettlement	Delete Settlement	User clicks Delete on an existing settlement
createPayoutsForWorksheet	Create Payouts from Settlement Items	Auto-called after settlement save; also called during the Settle transition
createPassthroughPayout	Create Passthrough Payment Payout	User adds a passthrough payout from the Payments tab
createVatPassthroughPayout	Create VAT Pass-Through Payout	Tax engine determines UK VAT applies to the artist fee
submitSettlementsForWorksheet	Submit Settlements for Worksheet	Worksheet Settle button clicked (Applied → Settled)
approveAllSettlementsForWorksheet	Approve Settlements for Worksheet	Worksheet Approve button clicked (Settled → Approved)
createPaymentItemsFromPayouts	Create Payment Items from Payouts	Worksheet approval — converts payout records into outbound payment requests
returnSettlementsForWorksheet	Return Settlements	Worksheet return initiated (Approved → Returned)
voidPaymentItemsForWorksheetReturn	Void Payment Items on Worksheet Return	Worksheet return — voids unlocked payment items
updateDoNotSendFlag	Update Payment Item Do-Not-Send Flag	User toggles "Do Not Send" on a payout or payment item row

---

5. Key User Actions

5.1 Create Settlement

Preconditions:

• Worksheet cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'P' (Applied)
• At least one PAY-type application row is selected via checkbox in the Receivables table
• Selected rows belong to the same deal (billing_item.deal_id)
• User has the CASH_PROCESSOR or IT role

Procedure reference: Create Settlement

Steps:

1. User selects one or more PAY receivable rows using row checkboxes in the Receivables table.
2. The "Create Settlement" button becomes visible in the table action area.
3. User clicks "Create Settlement." The settlement form opens pre-populated with deal party commission defaults from computeSettlementDefaults.
4. User reviews and adjusts commission amounts, bank accounts, payment dates, and the calc_level_cd for each party.
5. User clicks Save. The system validates the settlement total against PAY applied. On success, the settlement is created.

Postconditions:

• participant_settlement record exists with participant_settlement_status_cd = 'D'.
• participant_settlement_item records exist for each non-zero payee.
• cash_receipt_application.participant_settlement_id is set for all linked applications.
• cash_receipt_payout records of type 'S' are created for each qualifying item.

UI trigger: "Create Settlement" button. Visible when cash_receipt_worksheet_status_cd = 'P' and at least one PAY row is checked. Enabled when all selected rows belong to the same deal.

---

5.2 Edit Settlement

Preconditions:

• Worksheet is in Applied status ('P')
• Settlement is not fully locked (is_read_only = false at the header level — no locked payment items)
• User has the CASH_PROCESSOR or IT role

Procedure reference: Update Settlement

Steps:

1. User clicks the settlement badge on a receivable row in the Receivables table.
2. The settlement form opens showing the current values.
3. User modifies commission amounts, parties, bank accounts, or payment dates.
4. User clicks Save. The system re-validates the total, voids any changed unlocked payment items, updates settlement items, and re-links applications.

Postconditions:

• participant_settlement and participant_settlement_item records reflect updated values.
• Changed unlocked payment items have payment_execution_status_cd = 'CANCELLED' and payment_item_posting_status_cd = 'X'.
• cash_receipt_payout records are updated to reflect the new amounts.
• Locked items are unchanged.

UI trigger: Settlement badge on a receivable row. Visible when a settlement exists for that row. The form renders as editable when no locked items exist; as read-only when the header-level is_read_only = true.

---

5.3 Delete Settlement

Preconditions:

• Settlement has no locked payment items (has_locked_payments = false from checkLockedPaymentsForDeletion)
• Worksheet is in Applied status ('P')
• User has the CASH_PROCESSOR or IT role

Procedure reference: Delete Settlement

Steps:

1. User opens the settlement form for an existing settlement.
2. User clicks the Delete button.
3. The system checks for locked payments. If locked, an error toast is shown and deletion is blocked.
4. If no locked payments: unlocked payment items are voided, payouts deleted, applications unlinked, and the settlement removed.

Postconditions:

• participant_settlement and all participant_settlement_item records are deleted.
• cash_receipt_payout records for this settlement are deleted.
• cash_receipt_application.participant_settlement_id is set to NULL for all previously linked applications.
• Unlinked applications become eligible for a new settlement.

UI trigger: "Delete" button within the settlement form. Visible only when no items are locked.

---

5.4 Settle Worksheet (Applied → Settled)

Preconditions:

• cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'P' (Applied)
• All PAY applications on the worksheet have cash_receipt_application.participant_settlement_id set (not null)
• User has the CASH_PROCESSOR or IT role

Procedure reference: Submit Settlements for Worksheet

Steps:

1. User verifies all PAY rows in the Receivables table have settlement badges.
2. User clicks "Settle." The system ensures all payout records exist (idempotent call to createPayoutsForWorksheet) and bulk-updates all settlement statuses to Settled.
3. Worksheet transitions to cash_receipt_worksheet_status_cd = 'T'.

Postconditions:

• cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'T'.
• cash_receipt_worksheet.settled_dt and cash_receipt_worksheet.settled_by populated.
• All linked participant_settlement.participant_settlement_status_cd = 'T'.
• All cash_receipt_payout records of type 'S' exist for every settlement item.

UI trigger: "Settle" button in the worksheet action panel. Visible when cash_receipt_worksheet_status_cd = 'P' and user has CASH_PROCESSOR or IT role. Disabled with tooltip when hasUnsettledPayApplications = true.

---

5.5 Approve Worksheet (Settled → Approved)

Preconditions:

• cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'T' (Settled)
• User has the SETTLEMENT_APPROVER or IT role

Procedure reference: Approve Settlements for Worksheet

Steps:

1. User reviews the settled worksheet and its settlement details.
2. User clicks "Approve." The system approves all settlements, creates payment_item records from the cash_receipt_payout records, and transitions the worksheet.

Postconditions:

• cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'A'.
• cash_receipt_worksheet.approved_dt and cash_receipt_worksheet.approved_by populated.
• All participant_settlement.participant_settlement_status_cd = 'A'.
• payment_item records exist for each qualifying payout, each with payment_item_posting_status_cd = 'U'.
• Payment items with a current or past payment_date have payment_execution_status_cd = 'PENDING'.
• Payment items with a future payment_date or do_not_send_ind = true have payment_execution_status_cd = 'WAITING'.
• cash_receipt_payout.payment_item_id and participant_settlement_item.payment_item_id back-linked.

UI trigger: "Approve" button in the worksheet action panel. Visible when cash_receipt_worksheet_status_cd = 'T' and user has SETTLEMENT_APPROVER or IT role.

---

5.6 Add Passthrough Payout

Preconditions:

• Worksheet is in Draft or Applied status (pre-approval, isDraft = true)
• User has the CASH_PROCESSOR or IT role

Procedure reference: Create Passthrough Payment Payout

Steps:

1. User navigates to the Payments tab on the worksheet.
2. User clicks "Add Payment."
3. User fills in: payee party, bank account, amount, payment type ('P'), payment date, and optional deal context.
4. User saves. A cash_receipt_payout record with payment_item_type_cd = 'P' is created immediately.

Postconditions:

• cash_receipt_payout record with payment_item_type_cd = 'P' and payment_item_id = NULL.
• Payout appears in the Payments tab grid.

UI trigger: "Add Payment" button on the Payments tab. Visible when isDraft = true and !isReadOnly.

---

5.7 Toggle Do-Not-Send

Preconditions:

• Payout exists (pre-approval) or payment item exists (post-approval)
• Payment item is not in a locked status

Procedure reference: Update Payment Item Do-Not-Send Flag

Steps:

1. User checks or unchecks the "Do Not Send" checkbox on a payout or payment item row.
2. The system updates payment_item.do_not_send_ind (post-approval) or cash_receipt_payout.do_not_send_ind (pre-approval).

Postconditions:

• do_not_send_ind updated on the target record.
• If set to true: payment item will remain in WAITING status and not be picked up for bank transmission.
• If set to false: payment item becomes eligible for transmission if payment_date is current or past.

UI trigger: "Do Not Send" checkbox on Payments tab rows. Visible on all non-locked payouts and payment items.

---

6. Permissions & Role-Based Access

Action	CASH_MANAGER	CASH_PROCESSOR	SETTLEMENT_APPROVER	IT
Create settlement	—	Yes	—	Yes
Edit settlement	—	Yes	—	Yes
Delete settlement	—	Yes	—	Yes
Settle worksheet (Applied → Settled)	—	Yes	—	Yes
Approve worksheet (Settled → Approved)	—	—	Yes	Yes
Reopen worksheet (Approved → Returned)	—	—	Yes	Yes
Add passthrough payout	—	Yes	—	Yes
Toggle do-not-send flag	—	Yes	Yes	Yes
View settlements (read-only)	Yes	Yes	Yes	Yes

Field-level restrictions:

• Locked settlement items (is_read_only = true) are always read-only regardless of role. No user can modify or delete a settlement item whose linked payment item has payment_execution_status_cd IN ('PROCESSING', 'SENT', 'ACKNOWLEDGED', 'PAID').
• Settlement forms on Approved or Returned worksheets are fully read-only for all roles.
• The "Create Settlement" button only appears on Applied worksheets. On Draft worksheets, settlements cannot be created.

---

7. Integration Points

7.1 Upstream

Source	Data Provided	Mechanism
Worksheets Workflow	cash_receipt_application records with PAY-type billing item details; worksheet must be in Applied status before settlements can be created	FK lookup: cash_receipt_application.cash_receipt_worksheet_id
Billing Items	Deal context (deal_id, client_id, buyer_id, uta_entity_id, department_id), PAY total amounts, deduction amounts for commission calculation	FK: cash_receipt_application.billing_item_detail_id → billing_item_detail → billing_item
Deal Parties	Commission defaults (percentage, flat amount, bank account) pre-populated in the settlement form	FK: billing_item.deal_id → deal_party joined to party and bank_account
Tax Engine	Triggers VAT pass-through payout creation when UK VAT on artist fee applies to a worksheet receivable	Service call from the worksheet tax calculation flow

7.2 Downstream

Consumer	Data Consumed	Mechanism
Payments Workflow	payment_item records with payment_execution_status_cd = 'PENDING' or 'WAITING'; picks up PENDING items for bank transmission	FK: cash_receipt_payout.payment_item_id → payment_item
GL Posting Batch	payment_item records with payment_item_posting_status_cd = 'U' after bank confirmation (ACKNOWLEDGED or PAID)	Batch job queries payment_item where posting_status_cd = 'U'
Worksheet Return	Locked payment items and settlements are copied as read-only context to replacement drafts; unlocked items are voided	Called by the worksheet return procedure

7.3 External Integrations

No external integrations are initiated directly from the Settlements workflow. Bank transmission is handled by the Payments workflow after payment_item records are created at approval. See Payments Workflow for the bank adapter integration details.

---

8. Functional Screen Requirements

8.1 Worksheet Detail — Receivables Table (Settlement Context)

Route: /worksheets/[id]

Data loading:

• getSettlementsByWorksheetId — Get Settlements by Worksheet ID — loads all settlements on this worksheet to render settlement badges on receivable rows

Receivables Table Region

Displays all cash applications on the worksheet. PAY-type rows show settlement status badges and support checkbox selection for settlement creation.

Field / Column	Source	Editable?	Condition
Checkbox	UI selection state	Yes	Visible when cash_receipt_worksheet_status_cd = 'P' and row is PAY-type
Billing item / Revenue item name	revenue_items.revenue_item_name via billing_item_detail → billing_item	No	Always visible
REV / PAY type indicator	billing_item_detail.billing_item_detail_type_cd	No	Always visible
Applied amount	cash_receipt_application.cash_receipt_amt_applied	Yes (when Draft)	Editable in Draft; read-only in Applied and later
Settlement badge	participant_settlement.participant_settlement_status_cd via cash_receipt_application.participant_settlement_id	No — click to open form	Visible when participant_settlement_id IS NOT NULL
Lock icon	Computed: is_read_only from lock status check	No	Visible when the linked settlement has is_read_only = true
Deduction badge	Computed from cash_receipt_application_deduction	No	Visible when deductions exist for this application

Grid features:

• Sortable columns: billing item name, type, applied amount
• Filters: none
• Row selection: multi-select checkbox — used to select PAY rows for settlement creation
• Pagination: no

Conditional display:

• "Create Settlement" button appears above the table when cash_receipt_worksheet_status_cd = 'P' and at least one PAY row is selected.
• Checkbox column visible only when cash_receipt_worksheet_status_cd = 'P'.
• Lock icon visible on rows whose settlement has header-level is_read_only = true.
• Settlement badge displays the settlement status code: D (Draft), T (Settled), A (Approved), R (Returned).

---

8.2 Settlement Form (Side Panel)

Route: Overlays /worksheets/[id] as a side panel; no independent route

Data loading:

• computeSettlementDefaults for new settlements — Compute Settlement Defaults
• getSettlementEnriched for existing settlements — Get Settlement Enriched

Header Region

Shows deal and revenue item context, billing totals, and amounts applied on the current worksheet.

Field / Column	Source	Editable?	Condition
Deal name	deal.deal_name via billing_item.deal_id	No	Always visible
Revenue item name	revenue_items.revenue_item_name via billing_item.revenue_item_id	No	Always visible
PAY total (billing)	SUM(billing_item_detail.billing_item_detail_total_amt) for PAY sibling details	No	Always visible
REV gross (billing)	SUM(billing_item_detail.billing_item_detail_gross_amt) for selected REV details	No	Always visible
Deductions applied	Computed: rev_deduction_applied + pay_deduction_applied	No	Always visible
REV applied	SUM(cash_receipt_application.cash_receipt_amt_applied) for REV applications	No	Always visible
PAY applied	SUM(cash_receipt_application.cash_receipt_amt_applied) for PAY applications	No	Always visible
Override indicator	participant_settlement.participant_settlement_overrided_ind	No	Visible when true
Comment	participant_settlement.participant_settlement_comment	Yes	When not locked

Settlement Items Region

One row per payee. Shows commission allocation for each deal party.

Field / Column	Source	Editable?	Condition
Payee name	party.display_name via participant_settlement_item.payment_party_id	No (display)	Always visible
Party role	party_role.party_role_type_cd	No	Always visible
Bank account	bank_account.bank_account_name via participant_settlement_item.payment_party_bank_id	Yes (selector)	When item not locked
Commission type	participant_settlement_item.participant_settlement_commission_flat_ind (true = flat, false = %)	Yes	When item not locked
Commission %	participant_settlement_item.participant_settlment_commission_perc	Yes	When commission_flat_ind = false and item not locked
Commission amount	participant_settlement_item.participant_settlement_commission_amt	Yes	When item not locked
Calculation level	participant_settlement_item.calc_level_cd (DNI or IGN)	Yes	When item not locked
Payment date	participant_settlement_item.payment_date	Yes	When item not locked
Do not send	participant_settlement_item.do_not_send_ind	Yes	When item not locked
Comment	participant_settlement_item.participant_settlement_item_comment	Yes	When item not locked
Lock icon	Computed: per-item is_read_only flag	No	When item is locked

Grid features:

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

Conditional display:

• Settlement total amount displayed below the items list. Shown in a validation-error state when total does not match PAY applied within 0.01.
• Save button disabled when total does not balance.
• Delete button visible only when no items are locked.
• All fields read-only when the header-level is_read_only = true (triggered by any locked item).
• "Add party" row available at the bottom when not locked, to manually add a new settlement item beyond deal defaults.

---

8.3 Worksheet Detail — Payments Tab

Route: /worksheets/[id] (Payments tab)

Data loading:

• getPaymentPayouts — Get Payment Payouts for Worksheet — loads all cash_receipt_payout records for this worksheet

Payments Grid Region

Displays all payout records on the worksheet. Settlement-derived payouts (type 'S') are created automatically when settlements are saved. Passthrough payouts (type 'P') and VAT passthroughs (type 'V') are entered manually or by the tax engine.

Field / Column	Source	Editable?	Condition
Deal	deal.deal_name via cash_receipt_payout.deal_id	No	Always visible
Payout Party	party.display_name via cash_receipt_payout.payout_party_id	No	Always visible
Bank Account	bank_account.bank_account_name via cash_receipt_payout.payment_party_bank_id	No	Always visible
Payment Type	cash_receipt_payout.payment_item_type_cd (displayed as label: Settlement / Passthrough / VAT / etc.)	No	Always visible
Payment Date	cash_receipt_payout.payment_date	No	Always visible
Payment Description	cash_receipt_payout.payment_item_name	No	Always visible
Currency	cash_receipt_payout.payment_item_currency_cd	No	Always visible
Status	payment_item.payment_execution_status_cd via cash_receipt_payout.payment_item_id	No	Visible post-approval when payment_item_id IS NOT NULL
Do Not Send	cash_receipt_payout.do_not_send_ind (pre-approval) or payment_item.do_not_send_ind (post-approval)	Yes	When not locked
Applied Amounts	cash_receipt_payout.payment_item_amt	Yes (for non-S types, pre-approval)	Editable for passthrough and non-settlement payouts in Draft; read-only for settlement-derived payouts (payment_item_type_cd = 'S')

Grid features:

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

Conditional display:

• "Add Payment" button visible when isDraft = true and !isReadOnly.
• Settlement-derived payouts (type 'S') cannot be edited or deleted from this tab; they are managed via the settlement form.
• Post-approval: locked payouts display a lock icon and payment_execution_status_cd badge in the Status column.
• A "Locked Payments" section separator appears on replacement drafts, showing locked payouts from the prior approved worksheet as informational context. These are read-only and cannot be deleted.
• Delete button visible only on unlocked passthrough payouts (payment_item_type_cd = 'P' or 'V').

---

8.4 Worksheet Detail — Action Buttons

Route: /worksheets/[id] (action panel)

Data loading: Worksheet status and user role data loaded with the worksheet page.

Action Panel Region

Shows workflow transition buttons appropriate to the current worksheet status and user role.

Field / Column	Source	Editable?	Condition
Apply button	N/A — triggers applyWorksheet action	N/A	cash_receipt_worksheet_status_cd = 'D' and user has CASH_MANAGER or IT role
Settle button	N/A — triggers settleWorksheet action	N/A	cash_receipt_worksheet_status_cd = 'P' and user has CASH_PROCESSOR or IT role
Approve button	N/A — triggers approveWorksheet action	N/A	cash_receipt_worksheet_status_cd = 'T' and user has SETTLEMENT_APPROVER or IT role
Reject button	N/A — rolls back one step	N/A	Same conditions as Settle / Approve
Reopen Worksheet button	N/A — triggers reopenWorksheet action	N/A	cash_receipt_worksheet_status_cd = 'A', user has SETTLEMENT_APPROVER or IT role, replaced_by_worksheet_id IS NULL, and !isWriteOff

Conditional display:

• Settle button disabled with tooltip "Create settlements for all PAY applications before settling" when hasUnsettledPayApplications = true.
• Reopen Worksheet button hidden when replaced_by_worksheet_id IS NOT NULL (worksheet has already been returned and replaced).
• Reopen Worksheet button hidden for write-off worksheets (worksheet_type_cd indicates write-off context).
• All action buttons hidden when isReadOnly = true (returned worksheet).

---

9. Additional Diagrams

Settlement Status Lifecycle

stateDiagram-v2
    [*] --> D : Settlement created
    D --> T : Worksheet transitions to Settled
    T --> A : Worksheet transitions to Approved
    A --> R : Worksheet returned
    A --> P : All payment items reach PAID

Settlement status values: D (Draft), T (Settled), A (Approved), R (Returned), P (Paid). Forward-only — no backward transitions.

---

Payment Item Execution Lifecycle

stateDiagram-v2
    [*] --> WAITING : Future date or do_not_send_ind = true
    [*] --> PENDING : Ready immediately
    WAITING --> PENDING : Date arrives or hold released
    PENDING --> PROCESSING : Payment processor locks item
    PROCESSING --> SENT : Bank API call succeeds
    PROCESSING --> PENDING : Bank API call fails (retry eligible)
    SENT --> ACKNOWLEDGED : Bank confirms via poll
    SENT --> FAILED : Bank reports failure via poll
    ACKNOWLEDGED --> PAID : Bank confirms funds transferred
    FAILED --> PENDING : Retry
    PENDING --> CANCELLED : Worksheet return voids unlocked item

Locked statuses (cannot reverse or modify): PROCESSING, SENT, ACKNOWLEDGED, PAID. Unlocked statuses: WAITING, PENDING, FAILED, CANCELLED, null.

---

Settlement Creation Sequence

sequenceDiagram
    participant CP as Cash Processor
    participant WS as Worksheet
    participant ST as Settlement
    participant PO as cash_receipt_payout
    participant PI as payment_item

    CP->>WS: Apply (D → P)
    CP->>ST: Create Settlement for PAY rows
    ST->>PO: Auto-create payouts (type S)
    CP->>WS: Settle (P → T)
    WS->>ST: Bulk-update status → T
    CP->>WS: Approve (T → A)
    WS->>ST: Bulk-update status → A
    WS->>PI: Create payment_item from payout (one per non-zero payout)
    PI-->>PO: Back-link payment_item_id
    PI-->>ST: Back-link payment_item_id on settlement item

---

10. Cross-References

Document	Relationship
Settlements Data Model	Defines participant_settlement, participant_settlement_item, payment_item, outbound_payment_execution tables; status lifecycles; code master values; validation rules
Settlements Queries	Specifies all data retrieval operations including settlement defaults, lock status computation, payout lookup, and payment item enrichment
Settlements Procedures	Specifies all data mutation operations: create/update/delete settlement, payout creation, payment item creation, status transitions, void and cancellation
Worksheets Data Model	cash_receipt_application.participant_settlement_id links PAY applications to settlements; cash_receipt_payout bridges worksheet to payment items; worksheet status lifecycle drives all settlement status transitions
Worksheets Workflow	Upstream: worksheet must reach Applied status before settlements can be created; worksheet lifecycle transitions (Settle, Approve, Return) drive all settlement status changes
Payments Workflow	Downstream: payment_item records created at worksheet approval are consumed by the Payments workflow for bank transmission, status polling, GL posting, and retry

---

11. Gherkin Scenarios

Feature: Settlements - Create and Balance Settlement

  Scenario: Cash Processor creates a settlement for a single PAY application
    Given a worksheet for "Taylor Swift - Madison Square Garden 2026" deal is in Applied status
    And the worksheet has a PAY application with cash_receipt_application.cash_receipt_amt_applied = 8500.00
    And the deal has two deal parties: Taylor Swift (85%) and CAA Management (15%)
    When the Cash Processor selects the PAY row checkbox
    And clicks "Create Settlement"
    Then the settlement form opens pre-populated with:
      | Party          | Commission % | Commission Amt |
      | Taylor Swift   | 85.0000      | 7225.00        |
      | CAA Management | 15.0000      | 1275.00        |
    And the PAY applied reference shows 8500.00
    When the Cash Processor clicks Save without modifying values
    Then a participant_settlement record is created with participant_settlement_status_cd = 'D'
    And two participant_settlement_item records exist for Taylor Swift and CAA Management
    And cash_receipt_application.participant_settlement_id is set for the linked application
    And two cash_receipt_payout records exist with payment_item_type_cd = 'S' and amounts 7225.00 and 1275.00

  Scenario: Settlement total does not balance against PAY applied
    Given a worksheet in Applied status with a PAY application of cash_receipt_amt_applied = 10000.00
    When the Cash Processor opens the Create Settlement form
    And changes Taylor Swift's commission amount to 7000.00 (leaving CAA Management at 1500.00)
    And clicks Save
    Then the system returns an error: "Settlement total (8500.00) must equal PAY Applied (10000.00)"
    And no participant_settlement record is created
    And the form remains open for correction

  Scenario: Settlement pre-populated using net PAY base when calc_level_cd = DNI
    Given a worksheet in Applied status with a PAY application of 10000.00
    And a cash_receipt_application_deduction with deduction_amt_applied = 500.00 on the PAY application
    And the settlement form is opened with calc_level_cd = 'DNI' (default)
    Then commission calculations use base_amount = 9500.00 (10000.00 minus 500.00)

  Scenario: All selected receivables must belong to the same deal
    Given a worksheet in Applied status with PAY applications from two different deals (deal_id 10 and deal_id 11)
    When the Cash Processor selects both PAY rows and attempts to click "Create Settlement"
    Then the "Create Settlement" button is disabled or the form returns a validation error
    And no participant_settlement record is created

Feature: Settlements - Settle and Approve Worksheet

  Scenario: Cash Processor settles a worksheet after creating settlements for all PAY applications
    Given a worksheet in Applied status
    And all PAY applications have cash_receipt_application.participant_settlement_id set (not null)
    And hasUnsettledPayApplications = false
    When the Cash Processor clicks Settle
    Then cash_receipt_worksheet.cash_receipt_worksheet_status_cd is set to 'T'
    And cash_receipt_worksheet.settled_dt is populated with the current timestamp
    And all participant_settlement records on this worksheet have participant_settlement_status_cd = 'T'

  Scenario: Settle button disabled when a PAY application lacks a settlement
    Given a worksheet in Applied status
    And two PAY applications exist on the worksheet
    And only one of them has cash_receipt_application.participant_settlement_id set
    Then hasUnsettledPayApplications = true
    And the Settle button is disabled with tooltip "Create settlements for all PAY applications before settling"
    When the Cash Processor creates a settlement for the remaining PAY application
    Then hasUnsettledPayApplications = false
    And the Settle button becomes enabled

  Scenario: Settlement Approver approves a settled worksheet, creating payment items
    Given a worksheet in Settled status
    And two participant_settlement records with participant_settlement_status_cd = 'T'
    And cash_receipt_payout records with payment_item_id = NULL
    When the Settlement Approver clicks Approve
    Then cash_receipt_worksheet.cash_receipt_worksheet_status_cd is set to 'A'
    And all participant_settlement records have participant_settlement_status_cd = 'A'
    And payment_item records are created for each qualifying cash_receipt_payout (payment_item_id IS NULL)
    And each payment_item has payment_item_posting_status_cd = 'U'
    And cash_receipt_payout.payment_item_id is back-linked to each new payment_item
    And participant_settlement_item.payment_item_id is back-linked to each new payment_item

  Scenario: Payment item created as PENDING for current-date payment
    Given a settlement item with payment_date = '2026-03-02' (today) and do_not_send_ind = false
    When the worksheet is approved
    Then the created payment_item has payment_execution_status_cd = 'PENDING'

  Scenario: Payment item created as WAITING for future-dated payment
    Given a settlement item with payment_date = '2026-06-01' and current date is 2026-03-02
    When the worksheet is approved
    Then the created payment_item has payment_execution_status_cd = 'WAITING'
    And the payment item does not enter the PENDING processing queue

Feature: Settlements - Lock Behavior

  Scenario: Settlement becomes read-only when its payment is sent to the bank
    Given a worksheet in Approved status
    And a participant_settlement_item with a linked payment_item having payment_execution_status_cd = 'SENT'
    When the Cash Processor views the settlement form for that settlement
    Then the settlement form header is_read_only = true
    And all settlement item fields are read-only
    And the Delete button is not visible

  Scenario: Cannot delete a settlement with a locked payment item
    Given a settlement with one participant_settlement_item where the linked payment_item.payment_execution_status_cd = 'SENT'
    When a user attempts to delete the settlement
    Then the system returns an error: "Cannot delete settlement with locked payment items. One or more payments have been sent to the bank."
    And the participant_settlement record is not deleted

  Scenario: Editing an unlocked settlement item voids the existing payment item
    Given a settlement in Approved status where one payment_item has payment_execution_status_cd = 'PENDING'
    When the Cash Processor edits the commission amount for that settlement item
    And clicks Save
    Then the existing payment_item is updated with payment_execution_status_cd = 'CANCELLED' and payment_item_posting_status_cd = 'X'
    And the return_reason_cd on the payment_item is set to 'SETTLEMENT_EDIT'
    And a new cash_receipt_payout record is created with the updated amount

Feature: Settlements - Worksheet Return and Locking

  Scenario: Worksheet return voids unlocked payments and preserves locked ones
    Given an Approved worksheet with two settlements:
      - Settlement A has a payment_item with payment_execution_status_cd = 'SENT' (locked)
      - Settlement B has a payment_item with payment_execution_status_cd = 'PENDING' (unlocked)
    When the Settlement Approver clicks "Reopen Worksheet" and confirms
    Then the original worksheet has cash_receipt_worksheet_status_cd = 'R' and current_item_ind = false
    And a reversal worksheet is created with worksheet_type_cd = 'REVERSAL' and negative entries for all applications
    And a replacement draft is created with worksheet_type_cd = 'REPLACEMENT' and current_item_ind = true
    And Settlement B's payment_item has payment_execution_status_cd = 'CANCELLED' and payment_item_posting_status_cd = 'X'
    And Settlement A's payment_item is unchanged (still payment_execution_status_cd = 'SENT')

  Scenario: Replacement draft does not pre-populate unlocked settlement applications
    Given a replacement draft created after worksheet return
    And the original worksheet had three PAY applications — one locked (payment SENT), two unlocked
    Then the replacement draft contains only the one locked PAY application as a read-only row
    And the two unlocked PAY applications are absent from the replacement draft
    And the Cash Processor must add fresh applications manually

Feature: Settlements - Passthrough Payments

  Scenario: Cash Processor adds a passthrough payment for a direct advance
    Given a worksheet in Draft status for client Kendrick Lamar
    When the Cash Processor opens the Payments tab
    And clicks "Add Payment"
    And enters payee: Kendrick Lamar's party_id, amount: 25000.00, payment_item_type_cd: 'P', payment_date: 2026-03-15
    And clicks Save
    Then a cash_receipt_payout record is created with payment_item_type_cd = 'P' and payment_item_amt = '25000.00'
    And payment_item_id = NULL on the payout (payment item created at approval)
    And the payout appears in the Payments tab grid

Feature: Settlements - GL Posting Rules

  Scenario: Voided payment item is marked Skipped, not Unposted
    Given an Approved worksheet with a payment_item having payment_execution_status_cd = 'PENDING'
    When the worksheet is returned
    Then the unlocked payment_item has payment_item_posting_status_cd = 'X'
    And payment_execution_status_cd = 'CANCELLED'
    And the GL posting batch does not pick up this payment item

  Scenario: Payment item GL posting status transitions to Posted after bank confirmation
    Given a payment_item with payment_execution_status_cd = 'ACKNOWLEDGED' and payment_item_posting_status_cd = 'U'
    When the GL posting batch runs
    Then payment_item.payment_item_posting_status_cd is set to 'P'
    And payment_item.posting_dt is populated with the posting date

**PoC Artifact:**

The bank transport layer in the PoC uses simulated responses based on specific cent values in payment amounts (e.g., an amount ending in .50 simulates a bank rejection). Production will replace the transport stub with real HTTP clients for each bank adapter. The settlement and payment item data model and workflow logic are production-ready; only the transport layer is a stub.