Mass Settlement Workflow

1. Executive Summary

Purpose

The Mass Settlement (MS) workflow provides a batch path for applying cash receipt splits to receivables and routing the resulting settlements through an agent approval process before funds are released to talent and their party. It is the primary entry point for settlement work, replacing the manual per-worksheet settlement flow for standard show collections.

Rather than requiring a Cash Processor to open each worksheet individually, create settlements one deal at a time, and advance each through its own approve cycle, Mass Settlement lets the operator stage all splits-to-receivables assignments in a single visual workspace, submit the group for agent review in one action, and release all funds simultaneously when the packet is approved. Behind the scenes, the system auto-creates worksheets, applications, and settlement defaults — the same records that the traditional workflow produces, but in bulk and driven by the packet's approval state rather than per-worksheet approvals.

Scope

Covered:

Building a settlement packet by staging cash receipt splits against billing item receivables (draft allocations)
Submitting the packet for agent approval
Agent approval and rejection flow
Release — the moment the system materializes worksheets, applies cash, creates settlements, and releases payment items to the bank queue
Passthrough payments, withholding tax (WHT), and VAT reconciliation within a packet
Commission-only (REV-only) receivables — settlement skipped, REV still posts
Document attachment requirements (management approval, signed deposit release)
Packet return after release

Not covered (documented separately):

The traditional per-worksheet settlement flow — see Settlements Workflow
Worksheet lifecycle (Apply, Settle, Approve, Return) — the MS release triggers these automatically; see Worksheets Workflow
Outbound payment transmission after payment items enter PENDING — see Payments Workflow
Settlement data model for settlement_packet, draft_allocation, settlement_packet_item — see Mass Settlement Data Model

Key Objectives

Consolidate the staging, approval, and release of multiple settlements into a single packet workflow.
Enforce agent sign-off before any funds move.
Auto-generate worksheets and settlement defaults at release so the Cash Processor never has to configure these manually.
Provide real-time split balance feedback as receivables are staged, preventing over-allocation.
Maintain a complete, immutable approval audit trail.

2. Process Overview

mermaid

flowchart TD
    A[Cash Processor opens Mass Settlement workspace] --> B[Selects a cash receipt split from Splits panel]
    B --> C[Clicks receivables in Receivables panel to add to queue]
    C --> D[Edits REV / PAY / PT amounts per queue row]
    D --> E{All receivables staged?}
    E -->|No| C
    E -->|Yes| F[Clicks 'Create Settlement']
    F --> G{Validation passes?}
    G -->|No — currency mismatch, over-allocation, missing PT party| H[Toast error — user corrects]
    H --> D
    G -->|Yes| I[System creates settlement_packet\nIN_PROGRESS → DRAFT\nOne worksheet per split, auto-applied and settled]
    I --> J[Cash Processor reviews packet on detail page]
    J --> K[Cash Processor clicks 'Submit for Approval']
    K --> L[Packet status → SUBMITTED]
    L --> M[Step 1 — Agent reviews and approves or rejects]
    M -->|Reject| N[REJECTED_AGENT → DRAFT\nSubmitter revises and resubmits]
    N --> L
    M -->|Approve| O[APPROVED_AGENT]
    O --> P[Step 2 — Submitter does final review and approves or rejects]
    P -->|Reject| Q[REJECTED_SUBMITTER → DRAFT]
    Q --> L
    P -->|Approve| R[APPROVED_SUBMITTER]
    R --> S[Step 3 — CAM reviews and approves or rejects]
    S -->|Reject| T[REJECTED_CAM → DRAFT]
    T --> L
    S -->|Approve| U[APPROVED_CAM]
    U --> V[Step 4 — VP Finance approves\nAuto-triggers release]
    V --> W[System releases packet:\n• All worksheets approved\n• payment_items created → PENDING\n• Settlement Summary PDF generated\nPacket status → RELEASED]
    W --> X{Return needed?}
    X -->|Yes| Y[RETURNED\nWorksheets reopened via 3-document model]
    X -->|No| Z[Terminal — packet closed]

Walkthrough

Open workspace — The Cash Processor navigates to /mass-settlement. The workspace shows a Splits panel (left), Receivables panel (right), and Settlement Queue (center). An optional client search bar filters all panels simultaneously.
Select a split — The operator clicks a cash receipt split in the Splits panel. The split's available balance is displayed. The Receivables panel reorders automatically, surfacing receivables with high match scores (green = payment term match, blue = sales item match) at the top.
Stage receivables — The operator clicks receivables one at a time to add them to the queue. Each click reserves cash from the split balance in real time. REV, PAY, and PT amounts are pre-populated from the billing item's balance but are fully editable per row.
Set amounts — For each queue row the operator can adjust: REV (UTA commission, stays in-house), PAY (client and party payout), and PT (passthrough — direct payment to a third party). If PT > 0, a payee party must be selected. The total applied across all rows for a split cannot exceed the split's available balance, but applying less than the full balance is permitted — the remaining balance stays available on the split for future use.
Create settlement — The operator clicks "Create Settlement." The system validates currency consistency, balance limits, and PT party presence. On success the packet transitions IN_PROGRESS → DRAFT:
- Draft allocations are converted to settlement_packet_item rows.
- One cash_receipt_worksheet is created per split.
- Cash is applied (REV and PAY applications created, worksheet → Applied P).
- Settlements are auto-created from deal party defaults (worksheet → Settled T).
- Passthrough payouts are created with do_not_send_ind = true — a hold that prevents bank transmission until the packet is released.
Review and submit — The operator reviews the packet on the detail page (/mass-settlement/packets/[id]). The Items table shows each receivable with its worksheet link and status. Tax compliance data (WHT, VAT) is displayed. When satisfied, the operator clicks "Submit for Approval," optionally setting the management approval and signed deposit release flags. Packet advances to SUBMITTED.
Four-step approval chain — The packet moves through four sequential approvers. Any approver can reject, which returns the packet to DRAFT for revision and resubmission. The chain does not carry partial credit — rejection resets the full chain.
Step Approver Advances to
1 Agent APPROVED_AGENT
2 Submitter (original submitter does final review) APPROVED_SUBMITTER
3 Client Accounting Manager (CAM) APPROVED_CAM
4 VP Finance RELEASED (auto)
Auto-release on VP Finance approval — When VP Finance approves an APPROVED_CAM packet, release is triggered automatically — no separate button. The system:
- Approves each linked worksheet (Settled T → Approved A).
- Creates payment_item records from settlement payouts.
- Clears do_not_send_ind on all payouts and payment items, advancing them to PENDING.
- Generates the Settlement Summary PDF.
- Sets packet status to RELEASED.
Payment transmission — The Payments workflow picks up PENDING payment items for bank transmission. No further action is required from the Cash Processor.
Return (if needed) — If a released packet must be unwound, the operator clicks "Return." This triggers the standard three-document worksheet return for each linked worksheet: the original is sealed, a reversal worksheet is auto-posted, and a replacement draft is created for re-entry.

Step	Approver	Advances to
1	Agent	`APPROVED_AGENT`
2	Submitter (original submitter does final review)	`APPROVED_SUBMITTER`
3	Client Accounting Manager (CAM)	`APPROVED_CAM`
4	VP Finance	`RELEASED` (auto)

3. Business Rules

3.1 Currency Must Be Consistent Across the Packet (Current Limitation)

Current behavior: All splits and receivables on a packet must share the same currency. Clicking a receivable whose currency differs from the selected split's currency triggers a toast error and the receivable is not added to the queue.

Requirement (not yet built): Cross-currency settlement is a documented requirement. A USD split should be usable to pay a GBP receivable. This requires a bank rate lock and currency conversion request routed through the bank API — the conversion happens on the bank side. The system would need to request a rate lock, receive the locked rate, convert the split amount to GBP at that rate, and apply the converted amount against the GBP receivable. The current same-currency enforcement is a placeholder until this capability is implemented.

NOTE

Cross-currency Mass Settlement (e.g., USD split → GBP receivable) is a future requirement. The bank-side rate lock and conversion API integration is not yet built. Do not treat the current toast-error enforcement as the intended long-term behavior.

3.2 Split Balance Cannot Be Exceeded

Business rule: The sum of REV + PAY + PT across all queue rows assigned to a given split cannot exceed that split's available balance.

Enforcement: Live balance feedback in the Splits panel. Attempting to add an amount that exceeds the balance triggers a validation error and blocks "Create Settlement."

3.3 Passthrough Party Is Required When PT > 0

Business rule: If a queue row has a PT (passthrough) amount greater than zero, a payee party must be selected for that row. A passthrough without a recipient is invalid.

Enforcement: Validation on "Create Settlement" click. If any row has pt_amt > 0 and no passthrough_party_id, an error is shown and the packet is not created.

3.4 Amounts Lock at Submission

Business rule: Once a packet transitions to SUBMITTED, the receivable amounts (REV, PAY, PT) are locked and cannot be edited. The figures are part of the agent's approval decision and must not change without a new submission.

Enforcement: The packet detail page renders all amount fields as read-only when packet_status_cd != 'DRAFT'. To change amounts, the packet must be rejected back to DRAFT and edited before resubmission.

3.5 Rejection Returns to DRAFT; Edit Reverts to Workspace

Business rule: When any approver rejects a packet, it returns to DRAFT status. From DRAFT the submitter has two options:

Resubmit as-is — Click "Resubmit." No changes to amounts. Packet returns to SUBMITTED and the full approval chain restarts from Step 1 (Agent).
Edit amounts — Click "Edit" on the packet detail page. The system tears down the materialized worksheets and applications, restores the receivables as draft allocations, and returns the packet to IN_PROGRESS. The Mass Settlement workspace opens with the receivables re-queued and fully editable. After making changes, click "Create Settlement" to re-materialize and then resubmit.

NOTE

When reverting to IN_PROGRESS via Edit, passthrough (PT) and WHT amounts are not restored — only REV and PAY amounts carry back. Passthrough amounts must be re-entered manually.

Enforcement: The Edit revert is blocked if any payment items linked to the packet are already in a locked status (SENT, ACKNOWLEDGED, or PAID), or if any linked worksheets are in Approved status.

3.6 Soft-Gate Document Flags Do Not Block Transitions

Business rule: The mgmt_approval_required and signed_deposit_release_required flags surface document upload tasks in the History panel but do not prevent submission or release. They are compliance visibility signals, not hard gates.

Enforcement: Status transitions proceed regardless of whether documents have been uploaded. The upload task badge remains visible until a document is attached.

3.7 One Worksheet Per Split

Business rule: During "Create Settlement," the system creates exactly one worksheet for each distinct cash_receipt_split_id in the packet. Multiple receivables sharing the same split are grouped onto a single worksheet.

Enforcement: Enforced in the createSettlements service. settlement_packet_item.cash_receipt_worksheet_id will be the same for all items sharing a split.

3.8 VP Finance Approval Auto-Triggers Release

Business rule: Release is not a separate user action. When VP Finance approves an APPROVED_CAM packet, releasePacket is called automatically. The system approves all linked worksheets, creates payment items, clears do_not_send_ind on all payouts and items (advancing from WAITING to PENDING), generates the Settlement Summary PDF, and sets the packet to RELEASED — all in one atomic operation triggered by the VP Finance approval.

Foundation reference: Mass Settlement Data Model — Transition: APPROVED_CAM → RELEASED

3.9 Draft Packets Can Be Deleted; Submitted Packets Cannot

Business rule: A packet in DRAFT, REJECTED_AGENT, REJECTED_SUBMITTER, or REJECTED_CAM status can be deleted. Deletion removes all linked worksheets, applications, and returns the reserved cash to the source splits. Once a packet is SUBMITTED or beyond, deletion is blocked — it must be processed through the approval workflow.

3.10 Commission-Only Receivables Do Not Generate Settlements

Business rule: A commission-only receivable is a billing item with a REV application but no PAY application — UTA is collecting only its commission, not handling the client's payout. The system does not create a participant_settlement for these items, because there is no PAY amount to divide among deal parties. The REV application still posts to the GL through the normal worksheet flow; only the settlement step is skipped.

3.11 WHT Is Separate From Passthrough

Business rule: Withholding tax (wht_amt, wht_type_cd on draft_allocation) is distinct from passthrough (passthrough_amt). WHT materializes as billing_item_tax records plus a payout to the tax authority at settlement creation time, and carries compliance-reporting obligations. Passthrough is a generic direct payment to a third party with no tax-compliance implications.

Foundation reference: Mass Settlement Data Model — draft_allocation

3.12 Packet Name Is Not an Identity

Business rule: packet_name is a human-readable label (auto-generated as MS-[ClientName]-[Timestamp]) and is not unique. The same client can have multiple packets per day for different deals or venues. Identity is always settlement_packet_id (UUID).

4. Data Access & Operations References

4.1 Key Procedures

Operation	When Triggered
Create packet + materialize worksheets	"Create Settlement" button clicked
Submit packet	"Submit for Approval" button clicked
Approve packet (agent)	Agent clicks Approve on Approvals dashboard
Reject packet (agent)	Agent clicks Reject with required reason
Resubmit packet	Cash Processor clicks Resubmit after rejection
Release packet	Auto-triggered when VP Finance approves an APPROVED_CAM packet
Return packet	Cash Processor clicks Return on released packet
Delete packet	Cash Processor deletes a DRAFT packet
Attach document	User uploads file in the Documents panel

4.2 Foundation References

Document	Referenced For
Mass Settlement Data Model	`settlement_packet`, `draft_allocation`, `settlement_packet_item`, `settlement_packet_status_history` table definitions and status lifecycles
Settlements Data Model	`participant_settlement`, `payment_item`, `payment`, `payment_line` — created during release
Worksheets Data Model	`cash_receipt_worksheet`, `cash_receipt_application` — auto-created during "Create Settlement"
Billing Items Data Model	`billing_item_tax` — WHT records created during materialization

5.1 Add Receivable to Queue

Preconditions:

A split is selected in the Splits panel
The receivable's currency matches the split's currency
The receivable has remaining balance

Steps:

Select a split (left panel) — available balance displayed.
Click a receivable row (right panel) — added to the queue immediately.
Adjust REV, PAY, PT amounts in the queue row as needed.
Repeat for additional receivables.

Postconditions:

Queue row exists with staged amounts.
Split balance reduced by the allocated total.
Receivable adjusted balance reduced.

5.2 Create Settlement (Materialize Packet)

Preconditions:

At least one receivable is in the queue
All currency constraints satisfied
PT amounts have a party assigned
Total allocation does not exceed any split's balance

Steps:

Review the queue — verify amounts, PT parties.
Click "Create Settlement."
System validates, then creates the packet and materializes worksheets.
Browser navigates to the packet detail page.

Postconditions:

settlement_packet created in DRAFT.
One cash_receipt_worksheet per split, each in T (Settled) status.
cash_receipt_application rows created for all REV and PAY amounts.
participant_settlement records created from deal party defaults.
Passthrough cash_receipt_payout rows created with do_not_send_ind = true (held until release clears the flag).
draft_allocation rows deleted.

5.3 Submit for Approval

Preconditions:

Packet packet_status_cd = 'DRAFT'
User has CASH_PROCESSOR or IT role

Steps:

Review the packet detail page — items, tax compliance, splits.
Click "Submit for Approval."
Optionally check "Management Approval Required" and/or "Signed Deposit Release Required" in the submit dialog.
Confirm submission.

Postconditions:

packet_status_cd = 'SUBMITTED'.
submitted_dt and submitted_by_user_id set.
Document upload tasks visible in History panel if flags were checked.
Status history record written (SUBMIT).
Packet appears in agent's Approvals dashboard.

5.4 Approve Packet (Agent)

Preconditions:

Packet packet_status_cd = 'SUBMITTED'
User has the agent role assigned as current_approver_role

Steps:

Navigate to Approvals dashboard (/mass-settlement/approvals).
Click Approve on the packet row (or from the packet detail page).
Confirm approval.

Postconditions:

packet_status_cd = 'APPROVED_AGENT'.
approved_dt and approved_by_user_id set.
Status history record written (APPROVE).
Packet advances to the Submitter review queue.

5.5 Reject Packet (Any Approver)

Preconditions:

Packet packet_status_cd matches the approver's current step (SUBMITTED, APPROVED_AGENT, or APPROVED_SUBMITTER)
User is the current step's approver role

Steps:

Click Reject on the Approvals dashboard or packet detail page.
Enter a rejection reason (required).
Confirm rejection.

Postconditions:

packet_status_cd set to the corresponding rejection status (REJECTED_AGENT, REJECTED_SUBMITTER, or REJECTED_CAM), then immediately to DRAFT for revision.
rejection_reason, rejected_dt, rejected_by_user_id set.
Status history record written (REJECT).
Submitter notified; "Resubmit" button appears. Full approval chain resets.

5.6 Resubmit After Rejection

Preconditions:

Packet packet_status_cd = 'DRAFT' (post-rejection)
User has CASH_PROCESSOR or IT role

Steps:

Review the rejection reason in the History panel.
To resubmit without changes: click "Resubmit" — packet returns to SUBMITTED, full approval chain restarts.
To change amounts before resubmitting: click "Edit" instead — see 5.8 Edit DRAFT Packet (Revert to Workspace).
Confirm resubmission.

Postconditions:

packet_status_cd = 'SUBMITTED'.
Status history record written (RESUBMIT).
Prior rejection fields preserved on the packet for audit.
Full approval chain restarts from Step 1 (Agent).

5.7 VP Finance Approval (Auto-Releases)

Preconditions:

Packet packet_status_cd = 'APPROVED_CAM'
User is VP Finance role

Steps:

Review the packet on the Approvals dashboard or packet detail page.
Click Approve.

Postconditions (triggered automatically):

All linked worksheets approved (T → A).
payment_item records created for each settlement payout.
do_not_send_ind cleared on all payouts and payment items → status advances to PENDING.
Payment items enter the bank transmission queue.
Settlement Summary PDF generated and available on the packet.
packet_status_cd = 'RELEASED'.
released_dt and released_by_user_id set.
Status history record written (RELEASE).
All settlement_packet_item.item_status_cd updated to RELEASED.

5.8 Edit DRAFT Packet (Revert to Workspace)

Preconditions:

Packet packet_status_cd = 'DRAFT' (including post-rejection DRAFT)
No payment items on the packet in a locked status (SENT, ACKNOWLEDGED, or PAID)
No linked worksheets in Approved status

Steps:

From the packet detail page, click the "Edit" button (pencil icon) in the packet header.
A confirmation dialog asks: "Edit packet — revert to In Progress?"
Confirm. The system:
- Tears down all materialized worksheets, applications, and settlements
- Restores the receivables as draft_allocation rows on the same packet
- Flips the packet back to IN_PROGRESS
The Mass Settlement workspace opens with the receivables re-queued in the settlement queue, amounts editable.
Adjust REV/PAY/PT amounts, add or remove receivables, then click "Create Settlement" to re-materialize.

Postconditions:

Packet packet_status_cd = 'IN_PROGRESS'.
Worksheets, applications, and settlements from the prior materialization are deleted.
Receivables are restored as draft_allocation rows with prior REV and PAY amounts. PT and WHT amounts are not restored — re-enter manually if needed.

5.9 Return Released Packet

Preconditions:

Packet packet_status_cd = 'RELEASED'
User has SETTLEMENT_APPROVER or IT role

Steps:

From the packet detail page, click "Return."
Enter a return reason (required).
Confirm.

Postconditions:

For each linked worksheet, the standard three-document return is executed: original sealed (R), reversal worksheet auto-posted, replacement draft created.
Unlocked payment items voided (CANCELLED, posting_status_cd = 'X').
Locked payment items preserved as read-only context on replacement drafts.
packet_status_cd = 'RETURNED'.
Status history record written (RETURN).

6. Permissions & Role-Based Access

Action	CASH_PROCESSOR	AGENT	SETTLEMENT_APPROVER	IT
Build queue / stage allocations	Yes	—	—	Yes
Create Settlement (materialize)	Yes	—	—	Yes
Submit for Approval	Yes	—	—	Yes
Resubmit after rejection	Yes	—	—	Yes
Delete DRAFT packet	Yes	—	—	Yes
Approve packet (any step)	—	Per role	—	Yes
Reject packet (any step)	—	Per role	—	Yes
Attach documents	Yes	Yes	—	Yes
Return released packet	—	—	Yes	Yes
View packet (read-only)	Yes	Yes	Yes	Yes

Field-level restrictions:

All amount fields (REV, PAY, PT) are read-only once the packet is SUBMITTED or beyond.
The packet detail page is fully read-only for all roles when packet_status_cd = 'RELEASED' or 'RETURNED'.
Document uploads are locked after RELEASED.

7. Integration Points

7.1 Upstream

Source	Data Provided	Used For
Cash Receipts	`cash_receipt_split` rows with available balances	Funding source for packet allocations
Billing Items	`billing_item`, `billing_item_detail`	Receivables staged in the queue
Deal Parties	`deal_party` commission percentages and bank accounts	Settlement defaults auto-populated at materialization
Tax Engine	WHT / VAT calculations per billing item	`wht_amt`, `billing_item_tax` records created at materialization

7.2 Downstream

Consumer	Data Produced	Mechanism
Worksheets Workflow	`cash_receipt_worksheet` in `T` status (pre-release); approved `A` (post-release)	Auto-created during "Create Settlement"; approved during release
Settlements Workflow	`participant_settlement`, `participant_settlement_item`	Auto-created during "Create Settlement" using deal party defaults
Payments Workflow	`payment_item` records in `PENDING` status	Created at release; picked up by payment processor for bank transmission
GL Posting Batch	Posted transactions after bank confirmation	Standard downstream from payment items; no MS-specific handling

8. Functional Screen Requirements

8.1 Mass Settlement Workspace

Route: /mass-settlement

Three-panel layout:

Panel	Content	Behavior
Left — Splits	All unmatched/partially-matched `cash_receipt_split` rows for the selected client	Click to select; selected split highlighted; available balance shown
Right — Receivables	`billing_item` rows with open balance	Sorted by match score when a split is selected; click to add to queue
Center — Queue	Staged allocations (one row per receivable per split)	REV/PAY/PT editable per row; live balance feedback

Match scoring (when a split is selected):

Green background: cash_receipt_reference on the split matches the receivable's payment term
Blue background: references match the receivable's sales item ref
No color: unmatched

Queue footer: Per-split totals and grand total. Shows remaining balance per split.

Action bar: "Create Settlement" button — enabled when queue is non-empty and all validations pass. Shows validation error toasts inline when clicked with invalid state.

8.2 Packet Detail Page

Route: /mass-settlement/packets/[id]

Sections:

Section	Content
Header	Packet name, client, status badge, created-by, date; action buttons conditional on status
Items table	One row per `settlement_packet_item`: deal, billing item, buyer, split, REV, PAY, PT, total, currency, worksheet link, item status
Splits table	Each `cash_receipt_split` on the packet with allocated amount
Tax Compliance panel	VAT reconciliation, WHT summaries, deductions per billing item
Documents panel	Upload/download for management approval and signed deposit release; read-only after RELEASED
History sidebar	Full `settlement_packet_status_history` timeline with icons, timestamps, roles, and comments

Conditional action buttons:

Status	Buttons Shown
`IN_PROGRESS`	Create Settlement (in workspace), Delete
`DRAFT`	Submit for Approval, Delete
`SUBMITTED`	Approve / Reject (Agent only); none for Cash Processor
`APPROVED_AGENT`	Approve / Reject (Submitter only)
`APPROVED_SUBMITTER`	Approve / Reject (CAM only)
`APPROVED_CAM`	Approve / Reject (VP Finance only) — Approve auto-triggers release
`REJECTED_AGENT` / `REJECTED_SUBMITTER` / `REJECTED_CAM`	Resubmit, Delete
`RELEASED`	Return
`RETURNED`	(none — terminal)

8.3 Approvals Dashboard

Route: /mass-settlement/approvals

Content: All packets with packet_status_cd = 'SUBMITTED' where current_approver_role matches the logged-in user's role.

Column	Source
Packet name	`settlement_packet.packet_name`
Client	`party.display_name` via `settlement_packet.client_id`
Submitted by / date	`settlement_packet.submitted_by_user_id` + `submitted_dt`
Total amount	`settlement_packet.total_settlement_amt`
Item count	`settlement_packet.receivable_count`

Row actions: Approve (inline), Reject (opens dialog requiring reason), View (navigates to detail page).

9. Additional Diagrams

Packet Status Lifecycle

mermaid

stateDiagram-v2
    [*] --> IN_PROGRESS : Staging (draft allocations)
    IN_PROGRESS --> DRAFT : Create Settlement (materialized)
    DRAFT --> SUBMITTED : Submit for Approval
    SUBMITTED --> APPROVED_AGENT : Agent approves
    SUBMITTED --> REJECTED_AGENT : Agent rejects
    APPROVED_AGENT --> APPROVED_SUBMITTER : Submitter approves
    APPROVED_AGENT --> REJECTED_SUBMITTER : Submitter rejects
    APPROVED_SUBMITTER --> APPROVED_CAM : CAM approves
    APPROVED_SUBMITTER --> REJECTED_CAM : CAM rejects
    APPROVED_CAM --> RELEASED : VP Finance approves (auto-releases)
    REJECTED_AGENT --> DRAFT : Revert to DRAFT for revision
    REJECTED_SUBMITTER --> DRAFT : Revert to DRAFT for revision
    REJECTED_CAM --> DRAFT : Revert to DRAFT for revision
    RELEASED --> RETURNED : Return

Release Sequence

mermaid

sequenceDiagram
    participant CP as Cash Processor
    participant PKT as settlement_packet
    participant WS as cash_receipt_worksheet
    participant PI as payment_item

    CP->>PKT: VP Finance approves (APPROVED_CAM → auto-release)
    loop For each linked worksheet
        PKT->>WS: approveWorksheet (T → A)
        WS->>PI: Create payment_items (WAITING, do_not_send=true)
    end
    PKT->>PI: clearDoNotSend for all items (WAITING → PENDING)
    PKT-->>CP: Settlement Summary PDF generated
    Note over PI: Items now in PENDING — Payments workflow picks up

Materialization Sequence (Create Settlement)

mermaid

sequenceDiagram
    participant CP as Cash Processor
    participant PKT as settlement_packet
    participant WS as cash_receipt_worksheet
    participant ST as participant_settlement

    CP->>PKT: Create Settlement
    PKT->>PKT: Validate (currency, balance, PT party)
    PKT->>PKT: Create settlement_packet (DRAFT)
    loop For each split in queue
        PKT->>WS: Create worksheet
        WS->>WS: Apply cash (D → P)
        WS->>ST: Create settlements from deal party defaults
        WS->>WS: Settle worksheet (P → T)
    end
    PKT->>PKT: Delete draft_allocation rows
    PKT-->>CP: Navigate to packet detail page

10. Cross-References

Document	Relationship
Mass Settlement Data Model	`settlement_packet`, `draft_allocation`, `settlement_packet_item`, `settlement_packet_status_history` — the data layer this workflow operates against
Settlements Workflow	The traditional alternative path for creating settlements on individual worksheets. MS produces the same downstream records (`participant_settlement`, `payment_item`) but via a batch approval process rather than per-worksheet actions
Worksheets Workflow	Worksheets are auto-created during "Create Settlement" and auto-approved during Release. The three-document return model applies when a packet is returned
Payments Workflow	`payment_item` records released to `PENDING` status are consumed by the Payments workflow for bank transmission, status polling, and GL posting
Billing Items Data Model	`billing_item_tax` records created during materialization for WHT amounts staged in `draft_allocation.wht_amt`
Settlements Data Model	`participant_settlement`, `payment_item`, `payment`, `payment_line` — created at materialization and release

Sample Deals

Touring Deal

Endorsement Deal

Sports Endo Deal

Appendices

Appendices

Appendices

Mass Settlement Workflow ​

1. Executive Summary ​

Purpose ​

Scope ​

Key Objectives ​

2. Process Overview ​

Walkthrough ​

3. Business Rules ​

3.1 Currency Must Be Consistent Across the Packet (Current Limitation) ​

3.2 Split Balance Cannot Be Exceeded ​

3.3 Passthrough Party Is Required When PT > 0 ​

3.4 Amounts Lock at Submission ​

3.5 Rejection Returns to DRAFT; Edit Reverts to Workspace ​

3.6 Soft-Gate Document Flags Do Not Block Transitions ​

3.7 One Worksheet Per Split ​

3.8 VP Finance Approval Auto-Triggers Release ​

3.9 Draft Packets Can Be Deleted; Submitted Packets Cannot ​

3.10 Commission-Only Receivables Do Not Generate Settlements ​

3.11 WHT Is Separate From Passthrough ​

3.12 Packet Name Is Not an Identity ​

4. Data Access & Operations References ​

4.1 Key Procedures ​

4.2 Foundation References ​

5. Key User Actions ​

5.1 Add Receivable to Queue ​

5.2 Create Settlement (Materialize Packet) ​

5.3 Submit for Approval ​

5.4 Approve Packet (Agent) ​

5.5 Reject Packet (Any Approver) ​

5.6 Resubmit After Rejection ​

5.7 VP Finance Approval (Auto-Releases) ​

5.8 Edit DRAFT Packet (Revert to Workspace) ​

5.9 Return Released Packet ​

6. Permissions & Role-Based Access ​

7. Integration Points ​

7.1 Upstream ​

7.2 Downstream ​

8. Functional Screen Requirements ​

8.1 Mass Settlement Workspace ​

8.2 Packet Detail Page ​

8.3 Approvals Dashboard ​

9. Additional Diagrams ​

Packet Status Lifecycle ​

Release Sequence ​

Materialization Sequence (Create Settlement) ​

10. Cross-References ​

Mass Settlement Workflow

1. Executive Summary

Purpose

Scope

Key Objectives

2. Process Overview

Walkthrough

3. Business Rules

3.1 Currency Must Be Consistent Across the Packet (Current Limitation)

3.2 Split Balance Cannot Be Exceeded

3.3 Passthrough Party Is Required When PT > 0

3.4 Amounts Lock at Submission

3.5 Rejection Returns to DRAFT; Edit Reverts to Workspace

3.6 Soft-Gate Document Flags Do Not Block Transitions

3.7 One Worksheet Per Split

3.8 VP Finance Approval Auto-Triggers Release

3.9 Draft Packets Can Be Deleted; Submitted Packets Cannot

3.10 Commission-Only Receivables Do Not Generate Settlements

3.11 WHT Is Separate From Passthrough

3.12 Packet Name Is Not an Identity

4. Data Access & Operations References

4.1 Key Procedures

4.2 Foundation References

5. Key User Actions

5.1 Add Receivable to Queue

5.2 Create Settlement (Materialize Packet)

5.3 Submit for Approval

5.4 Approve Packet (Agent)

5.5 Reject Packet (Any Approver)

5.6 Resubmit After Rejection

5.7 VP Finance Approval (Auto-Releases)

5.8 Edit DRAFT Packet (Revert to Workspace)

5.9 Return Released Packet

6. Permissions & Role-Based Access

7. Integration Points

7.1 Upstream

7.2 Downstream

8. Functional Screen Requirements

8.1 Mass Settlement Workspace

8.2 Packet Detail Page

8.3 Approvals Dashboard

9. Additional Diagrams

Packet Status Lifecycle

Release Sequence

Materialization Sequence (Create Settlement)

10. Cross-References