# updateIncomingPayment

## Overview

Edits a **DRAFT** incoming payment before it is posted, applying a partial header patch and any combination of settlement edits in a single transaction. The header patch covers `paymentDate`, `totalAmount`, and `paymentAccountId` (cash/bank GL account); all fields are optional and only supplied fields are changed. Settlement edits are additive: the caller may add new allocations (`addSettlements`), patch existing ones by id (`updateSettlements`), or remove them by id (`removeSettlementIds`) in the same call. Only a DRAFT payment can be edited — a POSTED payment must be reversed with [reverseIncomingPayment](./reverseIncomingPayment.md). After all edits are applied the effective settlement set must not target the same `AccountReceivableDueScheduleLine` twice. `id` is the IncomingPayment id.

## Modules Commands Used

- [account-receivable] updateIncomingPayment

## Exception Handling

| Error Code | Description |
| --- | --- |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_NOT_FOUND | No incoming payment exists for the given ID. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_INVALID_STATUS | The payment is not in DRAFT status; only DRAFT payments can be edited. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_INVALID_AMOUNT | The payment amount is not a positive value. |
| ACCOUNT_RECEIVABLE_ACCOUNT_NOT_FOUND | The cash/bank payment account does not exist. |
| ACCOUNT_RECEIVABLE_ACCOUNT_INACTIVE | The cash/bank payment account is not ACTIVE. |
| ACCOUNT_RECEIVABLE_ACCOUNT_COMPANY_MISMATCH | The payment account belongs to a different company. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_SETTLEMENT_INVALID | A settlement allocation has an invalid amount or would duplicate a target due-schedule line. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_SETTLEMENT_NOT_FOUND | A settlement to patch or remove was not found on this payment. |
| ACCOUNT_RECEIVABLE_INCOMING_PAYMENT_TARGET_INELIGIBLE | A settlement target is not eligible (for example, the invoice is not posted). |