This is an automated email from the ASF dual-hosted git repository.
adamsaghy pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/fineract.git
The following commit(s) were added to refs/heads/develop by this push:
new 93ef69abb1 FINERACT-2317: Add documentation for approved amount
modification endpoints
93ef69abb1 is described below
commit 93ef69abb1b3a39296ce47857fe65522acad40b5
Author: mark.vituska <[email protected]>
AuthorDate: Tue Aug 5 16:48:09 2025 +0200
FINERACT-2317: Add documentation for approved amount modification endpoints
---
.../features/approved-amount-modification.adoc | 140 +++++++++++++++++++++
.../src/docs/en/chapters/features/index.adoc | 1 +
2 files changed, 141 insertions(+)
diff --git
a/fineract-doc/src/docs/en/chapters/features/approved-amount-modification.adoc
b/fineract-doc/src/docs/en/chapters/features/approved-amount-modification.adoc
new file mode 100644
index 0000000000..71104585e9
--- /dev/null
+++
b/fineract-doc/src/docs/en/chapters/features/approved-amount-modification.adoc
@@ -0,0 +1,140 @@
+= Approved amount modification on loans
+
+== Overview
+
+In Apache Fineract, after a loan is disbursed, it is possible to alter the
principal amount that the loan was approved with. This means that the amount to
be disbursed can be fine-tuned throughout the loan lifecycle. The approved loan
amount can either be modified directly or indirectly through different
endpoints.
+
+== Supported Loan Type
+
+Approved amount modifications are supported on all loan types.
+
+== Business Events
+
+* Triggers a new business event: Loan Approved Amount Changed
+
+== API Endpoints
+
+=== Modifying approved amount on loans
+
+Fineract supports the direct modification of the approved amount on loans
+
+* *Endpoint*: `/loans/<loan_id>/approved-amount`
+* *Alternative Endpoint*:
`/loans/external-id/<loan_external_id>/approved-amount`
+* *Method*: `PUT`
+
+[source,json]
+----
+{
+ "amount": 1000.0,
+ "locale": "en"
+}
+----
+
+==== Response Body
+
+[source,json]
+----
+{
+ "changes": {
+ "locale": "en",
+ "newApprovedAmount": 1000.0,
+ "oldApprovedAmount": 1500.0
+ },
+ "clientId": 6,
+ "groupId": 10,
+ "officeId": 2,
+ "resourceExternalId": "95174ff9-1a75-4d72-a413-6f9b1cb988b7",
+ "resourceId": 3
+}
+----
+
+==== Validations
+
+* The approved amount of the loan cannot be lower than the `total principal
disbursed + total expected principal + total principal from capitalized income
transactions`.
+* The approved amount of the loan cannot be set higher, than the proposed
amount of the loan or if `allow approved/disbursed over applied amount`
configuration is enabled then the calculated threshold.
+
+=== Modifying available disbursement amount on loans
+
+Fineract supports the indirect modification of the approved amount on loans.
This is called modifying the available disbursement amount.
+
+[IMPORTANT]
+====
+Available disbursement amount is only a calculated value used by this endpoint
to indirectly update the approved amount of the loan. It is not stored anywhere.
+====
+
+The approved amount is calculated as: `total principal disbursed + total
expected principal + total principal from capitalized income + "amount" from
the request`.
+
+* *Endpoint*: `/loans/<loan_id>/available-disbursement-amount`
+* *Alternative Endpoint*:
`/loans/external-id/<loan_external_id>/available-disbursement-amount`
+* *Method*: `PUT`
+
+[source,json]
+----
+{
+ "amount": 100.0,
+ "locale": "en"
+}
+----
+
+==== Response Body
+
+[source,json]
+----
+{
+ "changes": {
+ "locale": "en",
+ "newApprovedAmount": 100.0,
+ "oldApprovedAmount": 1000.0,
+ "newAvailableDisbursementAmount": 100.0,
+ "oldAvailableDisbursementAmount": 1000.0
+ },
+ "clientId": 6,
+ "groupId": 10,
+ "officeId": 2,
+ "resourceExternalId": "95174ff9-1a75-4d72-a413-6f9b1cb988b7",
+ "resourceId": 3
+}
+----
+
+==== Validations
+
+* The available disbursement amount cannot be lower than 0.
+* The approved amount of the loan cannot be set higher, than the proposed
amount of the loan or if `allow approved/disbursed over applied amount`
configuration is enabled then the calculated threshold. This means that the new
available disbursement amount cannot be higher than
`maximumLoanPrincipalThreshold - total principal disbursed - total expected
principal - total principal from capitalized income`
+
+=== Approved amount history
+
+Modifying the approved amount of the loan through either endpoint also creates
a history entry that can be used to observe the changes overtime.
+
+* *Endpoint*: `/loans/<loan_id>/approved-amount`
+* *Alternative Endpoint*:
`/loans/external-id/<loan_external_id>/approved-amount`
+* *Method*: `GET`
+
+==== Response Body
+
+[source,json]
+----
+[
+ {
+ "loanId": 152,
+ "externalLoanId": "9e058913-3de8-4f6e-9e09-4b2067c4bb91",
+ "newApprovedAmount": 800.000000,
+ "oldApprovedAmount": 1000.000000,
+ "dateOfChange": "2025-08-05T16:35:43.427229+02:00"
+ },
+ {
+ "loanId": 152,
+ "externalLoanId": "9e058913-3de8-4f6e-9e09-4b2067c4bb91",
+ "newApprovedAmount": 600.000000,
+ "oldApprovedAmount": 800.000000,
+ "dateOfChange": "2025-08-05T16:35:43.543779+02:00"
+ },
+ {
+ "loanId": 152,
+ "externalLoanId": "9e058913-3de8-4f6e-9e09-4b2067c4bb91",
+ "newApprovedAmount": 400.000000,
+ "oldApprovedAmount": 600.000000,
+ "dateOfChange": "2025-08-05T16:35:43.603855+02:00"
+ }
+]
+----
+
diff --git a/fineract-doc/src/docs/en/chapters/features/index.adoc
b/fineract-doc/src/docs/en/chapters/features/index.adoc
index 595c41714a..d2813c4550 100644
--- a/fineract-doc/src/docs/en/chapters/features/index.adoc
+++ b/fineract-doc/src/docs/en/chapters/features/index.adoc
@@ -4,3 +4,4 @@ This section covers specific features and functionality
available in Apache Fine
include::capitalized-income.adoc[leveloffset=+1]
include::buydown-fee.adoc[leveloffset=+1]
+include::approved-amount-modification.adoc[leveloffset=+1]