# AccountReceivableSettlement

## Description

AccountReceivableSettlement is the AR-owned allocation that applies or reverses one
AR settlement source against one AccountReceivableDueScheduleLine. It is not a
payment document, financial-accounting clearing record, bank settlement, or
bank-reconciliation record. The source is identified by `sourceType` and its
matching source-specific foreign key. Version 1 supports `INCOMING_PAYMENT`
through `incomingPaymentId`; later AR-owned instruments such as promissory notes
or customer refunds can add an enum value and a nullable source-specific foreign
key without changing the settlement model's identity.

The model records how much of a due-schedule obligation the source settles and
supports partial settlement, one source across several due schedules, and
several sources against one due schedule. Source aggregate commands govern
editing and effectiveness. Reversal creates a corresponding row linked to the
original through `reversalOfSettlementId`, so effect polarity is available on
the settlement row without inspecting a source header.

## Domain Model Definitions

### Model type

Standard

### Command Definitions

- [createIncomingPayment](../command/CreateIncomingPayment.md) - Optionally create initial settlement rows under a DRAFT payment
- [updateIncomingPayment](../command/UpdateIncomingPayment.md) - Incrementally add, update, or remove rows under a DRAFT payment
- [postIncomingPayment](../command/PostIncomingPayment.md) - Validate settlement eligibility and make the rows effective
- [reverseIncomingPayment](../command/ReverseIncomingPayment.md) - Create linked reversing settlement rows under the same payment

### Query Definitions

- None

### Models

- AccountReceivableSettlement

### Invariants

- `sourceType` identifies the source kind and exactly one matching source-specific foreign key is non-null
- Version 1 permits only `sourceType = INCOMING_PAYMENT`, which requires `incomingPaymentId`
- Each settlement references exactly one AccountReceivableDueScheduleLine
- A settlement amount is always positive; `reversalOfSettlementId` being non-null gives the row a restoring, negative effective sign
- A payment can contain at most one original settlement and one linked reversing settlement for the same due schedule line; payment commands enforce original-row uniqueness and `reversalOfSettlementId` prevents duplicate reversal of one row
- Settlement rows have no standalone lifecycle; their source aggregate commands govern mutation and effectiveness
- Rows under POSTED, REVERSED, and CANCELLED IncomingPayments are retained and immutable
- An original settlement under a POSTED or REVERSED payment increases the effective settled amount of its due schedule line
- A reversing settlement under a REVERSED payment decreases the effective settled amount of its due schedule line
- The cumulative effective settlement amount for POSTED and REVERSED payments cannot be negative or exceed the due schedule amount
- A normal settlement may target a due schedule line owned by a POSTED INVOICE or CREDIT_MEMO for the same company, customer, and currency as the payment
- A settlement amount is a positive applied magnitude; its cash-net and journal direction comes from the target document's `documentType`
- The signed settlement total for an IncomingPayment must equal the payment's positive `totalAmount`
- Each reversing settlement has the same due schedule line and amount as its original and references it through `reversalOfSettlementId`
- A new AR-owned source kind adds one closed `sourceType` value, one nullable `<source>Id` relation, source-aware uniqueness, and remaining-balance validation
- Cash execution, bank-statement matching, bank reconciliation, and GL open-item clearing remain outside this model
- Effective sign is derived from `reversalOfSettlementId`; the parent payment status determines whether the payment is posted, reversed, or cancelled

### Relationships

- **References IncomingPayment**: Version 1 settlements with `sourceType = INCOMING_PAYMENT` reference their source through `incomingPaymentId`
- **References AccountReceivableDueScheduleLine**: Each settlement allocates payment amount to one AR due installment
- **References AccountReceivableSettlement (reversal)**: A reversing settlement references its original through `reversalOfSettlementId`