# Get loan balances Endpoint: GET /people/{personId}/loans/{loanId}/balances Version: 2025-03-26 Security: oauth2, bearerAuth, apiKeyHeader ## Path parameters: - `personId` (string, required) A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier. - `loanId` (string, required) The unique identifier of the Loan we wish to retrieve. Can be Peach or lender's external identifier. ## Query parameters: - `isRounded` (boolean) If true, balances will be rounded to the closes 1 cent. - `skipYtd` (boolean) If true, skip year-to-date calculations. - `fast` (boolean) Perform a faster query that returns a pre-defined subset of attributes. When this query parameter is used, the `toEffectiveAt` parameter is ignored and only real-time balances are returned. To configure the subset of attributes, please contact the Peach team. - `toEffectiveDate` (string) Last day for which to fetch balances ## Response 200 fields (application/json): - `message` (string) Description of the server action or error. - `status` (integer) HTTP status code. - `data` (object) The up-to-date loan balances as of the time of inquiry. - `data.isLocked` (boolean) If true, the loan is in the middle of being updated or replayed. The returned data are not consistent. The caller should poll on the `Get loan lock status` endpoint. Once `isLocked`` becomes `false`, the caller should call this endpoint again to get consistent data. - `data.authorizedAmount` (number) The total amount of purchases in `authorized` status. `authorizedAmount` is used in the calculation of the following amounts: `availableCreditAmount`, `openToBuyAmount`, `utilizationAmount`. `authorizedAmount` is NOT used in the calculations of the following amounts: `overLimitAmount`. Only applicable to lines of credit. - `data.availableCreditAmount` (number) The available credit amount to use. If the borrower exceeded their credit limit, the `availableCreditAmount` will be zero. For lines of credit only: - `availableCreditAmount` takes into account `authorizedAmount`. Authorized purchases decrease the `availableCreditAmount`. - The amount can be greater than `creditLimitAmount`. It happens only when the total amount of payments made by the borrower plus the total amount of service credits exceeds the line or draw balance. Any future purchases will first deplete the overpayment amount (also called `reimbursementAmount`). Only applicable to lines of credit or installment loans with multi-advances. - `data.calculatedAt` (string) Timestamp when the balances were calculated. - `data.chargedOffBalances` (object) Charged-off balances represent balances that are charged-off. - `data.chargedOffBalances.chargedOffFeesAmount` (number) The fees portion of the `chargedOffTotalAmount`. - `data.chargedOffBalances.chargedOffInterestAmount` (number) The interest portion of the `chargedOffTotalAmount`. - `data.chargedOffBalances.chargedOffPrincipalAmount` (number) The principal portion of the `chargedOffTotalAmount`. - `data.chargedOffBalances.chargedOffTotalAmount` (number) The total charged-off balance sums charged-off principal, interest, and fees. - `data.creditLimitAmount` (number) The credit limit amount for the line or draw. Only applicable to line of credit or installment loan with multiple advances. For installment loans with multi-advances, it is the amount financed set at origination. - `data.dueBalances` (object) Due balances represent balances that are currently due. - `data.dueBalances.dueDrawFeesAmount` (number) The draw fees portion of `dueFeesAmount`. - `data.dueBalances.dueFeesAmount` (number) The fees portion of the `dueTotalAmount`. `dueFeesAmount` is the sum of `dueOriginationFeesAmount`, `dueDrawFeesAmount`, `dueLateFeesAmount`, `dueModificationFeesAmount`, and `dueMembershipFeesAmount`. - `data.dueBalances.dueInterestAmount` (number) The interest portion of the `dueTotalAmount`. - `data.dueBalances.dueLateFeesAmount` (number) The late fees portion of `dueFeesAmount`. - `data.dueBalances.dueMembershipFeesAmount` (number) The membership fees portion of `dueFeesAmount`. - `data.dueBalances.dueModificationFeesAmount` (number) The modification fees portion of `dueFeesAmount`. - `data.dueBalances.dueOriginationFeesAmount` (number) The origination fees portion of `dueFeesAmount`. - `data.dueBalances.duePrincipalAmount` (number) The principal portion of the `dueTotalAmount`. - `data.dueBalances.dueTotalAmount` (number) The total due balance sums due principal, interest, and fees. - `data.interestAndFeesAmounts` (object) Interest and fees amounts - `data.interestAndFeesAmounts.deferredInterestAccruedTotalAmount` (number) The total deferred interest accrued. - If the deferred interest promotion is exercised, the deferred interest is foregone and therefore this attribute will have a value of zero. In this scenario, the deferred interest amount will "move" to the `forgoneInterestDeferredAmount` attribute. - If the deferred interest promotion is not executed, the deferred interest is recognized as regular interest and therefore this attribute will have a value of zero. In this scenario, the deferred interest amount will "move" to the `interestAccruedTotalAmount` attribute. - `data.interestAndFeesAmounts.deferredInterestDiscountTotalAmount` (number) The total deferred interest discount. - `data.interestAndFeesAmounts.feesChargedYearToDateAmount` (number) The amount of fees charged year-to-date. - `data.interestAndFeesAmounts.forgoneInterestCapAmount` (number) The amount of foregone interest that exceeded the interest cap amount. This is only applicable to loans that had `totalInterestCapAmount` set to `true` at loan origination. - `data.interestAndFeesAmounts.forgoneInterestDeferredAmount` (number) The amount of interest that was foregone because of deferred interest promotions. This is only applicable to loans with deferred interest promotions that were not executed. - `data.interestAndFeesAmounts.forgoneInterestRoundingAmount` (number) The amount of interest that was forgone because of rounding. Applicable only to: 1. Lines of credit (and draws) with minimum payments 2. Lines of credit (and draws) with balloon amortization 3. Installment loans with balloon amortization - `data.interestAndFeesAmounts.interestAccruedTotalAmount` (number) The total interest accrued - net of interest discount and foregone interest - from the start of the loan to the date of inquiry. - `data.interestAndFeesAmounts.interestAccruedYearToDateAmount` (number) The amount of interest accrued year-to-date not including interest discounts and forgone interest. - `data.interestAndFeesAmounts.interestAccruedYearToDateForStatementAmount` (number) This amount should be used for statements. The amount of interest accrued year-to-date not including interest discounts and forgone interest. The Peach system accrues interest on a "following" day based on the principal balance at the end-of-day of a prior day. The interest effective date is the "following" day. For example, interest that accrues on `2022-01-01` is based on the principal balance at the end-of-day of `2021-12-13`. The interest is effectively booked to the ledger on `2022-01-01`. When summarizing year to date interest for a statement, the interest that was accrued effectively on `2022-01-01` should be part of the 2021 year (in the example above). This is the main difference between the `interestAccruedYearToDateAmount` and `interestAccruedYearToDateForStatementAmount` fields. - `data.interestAndFeesAmounts.interestDiscountTotalAmount` (number) The total interest discount from the start of the loan to the date of inquiry. - `data.loanStatus` (string) The current status of the loan. New loans must be created in `pending`, `originated` or `declined` status. `pending` - the loan is in the application stage. Loan `atOrigination` details and terms can be changed (via API). `originated` - the loan was signed by the borrower and originated by the lender. Loan `atOrigination` details cannot be changed. Originated loans do not start accruing interest until activated. `declined` - an application was declined. This is a terminal state. `active` - the loan is active. Most loans are expected to be active. `frozen` - the loan is temporarily frozen. The loan will not accrue any interest, no payments can be processed, and no notifications are sent to the borrower. `accelerated` - the loan was accelerated. The loan will not accrue any additional interest and the entire balance is due. `chargedOff` - the loan was charged off. `paidOff` - the loan was successfully paid off. `canceled` - the loan was canceled. Canceled loans are not shown in UI. This is a terminal state. Enum: "pending", "originated", "declined", "active", "frozen", "accelerated", "chargedOff", "paidOff", "canceled" - `data.nonAccrualBalances` (object) Non-accrual balances represent balances that are non-accrual. - `data.nonAccrualBalances.nonAccrualFeesAmount` (number) The fees portion of the `nonAccrualTotalAmount`. - `data.nonAccrualBalances.nonAccrualInterestAmount` (number) The interest portion of the `nonAccrualTotalAmount`. - `data.nonAccrualBalances.nonAccrualPrincipalAmount` (number) The principal portion of the `nonAccrualTotalAmount`. - `data.nonAccrualBalances.nonAccrualTotalAmount` (number) The total non-accrual balance sums non-accrual principal, interest, and fees. - `data.nonDueBalances` (object) Non-due balances represent balances that are not yet due. - `data.nonDueBalances.nonDueDrawFeesAmount` (number) The draw fees portion of `nonDueFeesAmount`. - `data.nonDueBalances.nonDueFeesAmount` (number) The fees portion of the `nonDueTotalAmount`. `nonDueFeesAmount` is the sum of `nonDueOriginationFeesAmount`, `nonDueDrawFeesAmount`, `nonDueLateFeesAmount`, `nonDueModificationFeesAmount`, and `nonDueMembershipFeesAmount`. - `data.nonDueBalances.nonDueInterestAmount` (number) The interest portion of the `nonDueTotalAmount`. - `data.nonDueBalances.nonDueLateFeesAmount` (number) The late fees portion of `nonDueFeesAmount`. - `data.nonDueBalances.nonDueMembershipFeesAmount` (number) The membership fees portion of `nonDueFeesAmount`. - `data.nonDueBalances.nonDueModificationFeesAmount` (number) The modification fees portion of `nonDueFeesAmount`. - `data.nonDueBalances.nonDueOriginationFeesAmount` (number) The origination fees portion of `nonDueFeesAmount`. - `data.nonDueBalances.nonDuePrincipalAmount` (number) The principal portion of the `nonDueTotalAmount`. - `data.nonDueBalances.nonDueTotalAmount` (number) The total non-due balance sums non-due principal, interest, and fees. - `data.openToBuyAmount` (number) The amount of available credit a borrower has based on the `utilizationAmount` and transactions' hold day end date. The difference between `availableCreditAmount` and the `openToBuyAmount` is that `availableCreditAmount` doesn't take into account transactions' hold days. In other words, `availableCreditAmount` is more optimistic. For lines of credit only: - `openToBuyAmount` takes into account `authorizedAmount`. Authorized purchases decrease the `openToBuyAmount`. Only applicable to lines of credit. - `data.outstandingBalances` (object) When a loan is `active`, outstanding balances combine non-due, due, and overdue balances. When a loan is `accelerated`, outstanding balances are equal to non-accrual balances. When a loan is `chargedOff`, outstanding balances are equal to charged-off balances. - `data.outstandingBalances.outstandingDrawFeesAmount` (number) The draw fees portion of `outstandingFeesAmount`. - `data.outstandingBalances.outstandingFeesAmount` (number) The fees portion of the `outstandingTotalAmount`. `outstandingFeesAmount` is the sum of `outstandingOriginationFeesAmount`, `outstandingDrawFeesAmount`, `outstandingLateFeesAmount`, `outstandingModificationFeesAmount`, and `outstandingMembershipFeesAmount`. - `data.outstandingBalances.outstandingInterestAmount` (number) The interest portion of the `outstandingTotalAmount`. - `data.outstandingBalances.outstandingLateFeesAmount` (number) The late fees portion of `outstandingFeesAmount`. - `data.outstandingBalances.outstandingMembershipFeesAmount` (number) The membership fees portion of `outstandingFeesAmount`. - `data.outstandingBalances.outstandingModificationFeesAmount` (number) The modification fees portion of `outstandingFeesAmount`. - `data.outstandingBalances.outstandingOriginationFeesAmount` (number) The origination fees portion of `outstandingFeesAmount`. - `data.outstandingBalances.outstandingPrincipalAmount` (number) The principal portion of the `outstandingTotalAmount`. - `data.outstandingBalances.outstandingTotalAmount` (number) The total outstanding balance sums outstanding principal, interest, and fees. Also called the loan payoff amount. If the loan is charged off, the outstanding totalAmount will be equal to the `chargedOffTotalAmount`. - `data.outstandingBalancesWithPromo` (object) Promotional balances represent various balances needed to be paid in order to exercise the same-as-cash or other promotional program. - `data.outstandingBalancesWithPromo.outstandingTotalAmount` (number) The remaining amount needed to be paid in order to exercise the same-as-cash or other promotional program. - `data.overLimitAmount` (number) The amount of credit used above the `creditLimitAmount` for the line of credit or draw. Calculation is `max(0, utilizationAmount - authorizedAmount - creditLimitAmount)`, meaning that the over limit amount will only be > 0 if utilization (without authorized purchases) is greater than credit limit. Otherwise, `overLimitAmount` will always be 0. For lines of credit only: - `overLimitAmount` doesn't take into account `authorizedAmount`. Authorized purchases don't impact the `overLimitAmount`. Only applicable to line of credits. - `data.overdueBalances` (object) Overdue balances represent balances that are overdue. - `data.overdueBalances.overdueDrawFeesAmount` (number) The draw fees portion of `overdueFeesAmount`. - `data.overdueBalances.overdueFeesAmount` (number) The fees portion of the `overdueTotalAmount`. `overdueFeesAmount` is the sum of `overdueOriginationFeesAmount`, `overdueDrawFeesAmount`, `overdueLateFeesAmount`, `overdueModificationFeesAmount`, and `overdueMembershipFeesAmount`. - `data.overdueBalances.overdueInterestAmount` (number) The overdue interest portion of the `overdueTotalAmount`. - `data.overdueBalances.overdueLateFeesAmount` (number) The late fees portion of `overdueFeesAmount`. - `data.overdueBalances.overdueMembershipFeesAmount` (number) The membership fees portion of `overdueFeesAmount`. - `data.overdueBalances.overdueModificationFeesAmount` (number) The modification fees portion of `overdueFeesAmount`. - `data.overdueBalances.overdueOriginationFeesAmount` (number) The origination fees portion of `overdueFeesAmount`. - `data.overdueBalances.overduePrincipalAmount` (number) The overdue principal portion of the `overdueTotalAmount`. - `data.overdueBalances.overdueTotalAmount` (number) The total overdue balance sums overdue principal, interest, and fees. - `data.overdueNumberDays` (integer) If the loan is currently overdue, this represents the number of days the loan has been overdue. - `data.paidBalances` (object) Paid balances represent the amounts paid to date. - `data.paidBalances.paidCreditsAmount` (number) The total amount of service credits applied to the loan until today. - `data.paidBalances.paidFeesAmount` (number) The total amount of fees paid until today. - `data.paidBalances.paidInterestAmount` (number) The total amount of interest paid until today. - `data.paidBalances.paidOverAmount` (number) Stores any excess amount that was not allocated to principal, interest or fees. - `data.paidBalances.paidPaymentsAmount` (number) The total amount of payments applied to the loan until today, excluding reimbursements. - `data.paidBalances.paidPrincipalAmount` (number) The total amount of principal paid until today. - `data.paidBalances.paidReimbursementsAmount` (number) The total amount of reimbursements applied to the loan until today. - `data.paidBalances.paidTotalAmount` (number) The total payment and service credits made from the start of the loan to the date of inquiry. Excludes reimbursements. - `data.reimbursementAmount` (number) The total amount that a lender owes to the borrower. After a reimbursement is processed, the amount is reduced accordingly. - `data.utilizationAmount` (number) The loan or draw utilization amount. In other words, the amount of credit used by the borrower. For lines of credit only: - The amount is calculated based on the loan type `creditLimit.utilizationCalculation` configuration. For example: line of credit utilization can be calculated as the sum of principal buckets only without any interest or fees. - `utilizationAmount` takes into account `authorizedAmount`. Authorized purchases increase the `utilizationAmount`. - The amount can be negative. Negative amount happens only when the total amount of payments made by the borrower plus the total amount of service credits exceeds the line or draw balance. Any future purchases will first deplete the overpayment amount (also called `reimbursementAmount`). Only applicable to line of credits or installment loans with multi-advances.