FINERACT-2317: Add documentation for approved amount modification endpoints

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"
+  }
+]
+----
+

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]