HomeGuidesAPI Reference


A `RepaymentOption` object returns all the financial details of a given Repayment Plan, properly calculated for your `Borrower` and their unique situation, allowing you to provide a unique Assessment tailored just for their needs—enabling them to compare various Repayment Plans against their current Repayment Plan, and choose a Plan that works best for their goals and needs.

Understand `total_paid` vs `total_cost`

**`total_paid`** is the sum of all monthly payments a borrower will make on a loan's current Repayment Plan over its lifetime.

With Income-Driven Repayment plans, there is sometimes a "tax bomb" at the end of their repayment term—any outstanding balance is forgiven, but treated as taxable income. Thus, **`total_cost`** provides the sum of `total_paid` plus the taxes owed on that forgiven amount (which is calculated and provided in the `amount_forgiven` and `estimated_tax_liability` properties). In other words,`total_cost` is the bottom line amount a borrower will pay to dispense of their loan on a `RepaymentOption`.

Understand `scheduled_monthly_payment` vs `starting_monthly_payment`

When you look at `RepaymentOption` objects, you will notice there are two monthly payment properties—`scheduled_monthly_payment` and `starting_monthly_payment`. Though confusing, these values are provided separately to help a borrower make the best financial decisions for their futures, not just during this historically anomalous time.

During the ongoing COVID forbearance period—currently scheduled to end 2023-06-30—**`scheduled_monthly_payment`** provides the monthly payment a borrower would pay _under normal conditions_.

On the other hand, **`starting_monthly_payment`** provides the monthly payment a borrower is expected to pay _during COVID forbearance_ (which should always be `0.00`).

When the COVID forbearance period ends, both `scheduled_monthly_payment` and `starting_monthly_payment` should hold identical values.

### Schema Definition

PropertyTypeFormatDescription
`action_items``array`
_Deprecated. Will be removed in API v2._
`amount_forgiven``number``float`Total amount of outstanding `Loan` balance that will be forgiven at the end of the current Repayment Plan's term.
`annual_snapshots``array`TODOTODO
`eligible_loans``array`[`Loan`](🔗)An `array` of `Loan` objects which meet the eligibility criteria for this `RepaymentOption`.
`estimated_tax_liability``number``float`Estimated tax bomb, or the amount a `Borrower` will have assessed as income based on total amount forgiven by their Repayment Plan.
`final_monthly_payment``number``float`The amount of the final monthly payment.
`ineligible_loans``array`[`Loan`](🔗)An `array` of `Loan` objects which **do not** meet the eligibility criteria for this `RepaymentOption`.
`ineligible_reasons``array``string`An `array` of reasons `Loans` or a `Borrower` may not meet eligibility criteria for this `RepaymentOption`.
`name``string`
The name of the Repayment Plan this `RepaymentOption` represents.
`number_of_payments``integer``int32`Total number of payments that will be made over the course of the repayment term.
`pslf_eligible``boolean`
Is this `RepaymentOption` eligible for PSLF forgiveness? _Defaults to `false`._
`repayment_plan``object`[`RepaymentPlan`](🔗)A `RepaymentPlan` object with full details on the Repayment Plan this `RepaymentOption` represents.
`scheduled_monthly_payment``number``float`The regular monthly payment a borrower would pay _under normal conditions_, but is unlikely to pay during COVID forbearance.
`starting_monthly_payment``number``float`The monthly payment a borrower is expected to pay _during COVID forbearance_ (which should always be `0.00`).
`total_cost``number``float`The sum of `total_paid` plus `estimated_tax_liability` owed on total `amount_forgiven`. In other words, `total_cost` is the bottom line amount a borrower will pay to dispense of their loan on the current Repayment Plan.
`total_paid``number``float`The sum of all monthly payments a `Borrower` will make on a loan's current Repayment Plan over its lifetime.

### Example