Loan Restructuring

Loan restructuring provides various options of changing an existing loan's behavior.



Please note that the below enhancements are only available on Canopy v2.


When operating lending programs, there are a variety of situations where you need to change the terms of a given installment loan. The best practices under why and when to do so can vary dramatically. For instance:

  • You may have a variable interest rate clause
  • You may have a program that allows borrowers to periodically draw additional funds, increasing the principal balance on the new loans
  • You may run a loan program with clauses for borrowers to refinance different loans at different times or consolidate loans with different interest rates
  • You may have a negotiated agreement with a specific borrower in response to a hardship situation.

Within Canopy’s system, the above scenarios can be achieved via our restructuring functionality.

Executing a Restructure

Executing a loan restructure can be done through the Canopy API or directly in CanopyOS.

API Restrcuture

Loan restructuring can be accessed directly by calling the following endpoint:

POST /accounts/{{account_id}}/line_items/restructures/loans

You’ll notice that body of the request accepts any of the same parameters as the body of the loan creation endpoint. These parameters will be used by the newly restructured loan, and can be used to modify the behavior of the loan's properties.

See our API docs for the full list of configuration options here.

CanopyOS Restructure

  1. A restructure can be done in CanopyOS by clicking on the Manage button from the account view or from the Manage button while viewing a specific loan and then selecting Loan Restructure.
  1. You can then choose which loans you want to restructure. Note that is you select more than one loan, all loans selected will be restructured into one new loan.
  1. You will then we taken to a screen where you can choose the configuration of the new loan.
  1. Clicking on Preview restructure will take you to the screen below which will allow you to review your changes before submitting them.
    On this screen, you can add a note as well providing future context to the purpose for the restructure.
    You will also have to click the checkbox before you are able to submit the changes indicating you understand the implications of doing a restructure
  1. Once you have submitted your changes, you may temporarily notice a new loan card that says generating. This is because restructures take a moment to process. This card will soon display your new loan details.

Changing Loan Policies

The restructuring endpoint offers a number of configurations that allow you to restructure a loan in order to change its terms. These configuration options include:

  1. Interest policies
  2. Fee policies
  3. Loan term
  4. Minimum payment calculation type

Please note that if a selection is not made for these configuration options, the restructure will default them to the associated account level policy.

Handling Outstanding Interest & Fees

At the time of a restructure, it is possible that in addition to the outstanding principal balance, there may also be outstanding interest and fee balances on the loan. You have a few different options when it comes to handling these balances:

  1. Prior borrower pay off: Prior to executing the restructure, you can request the borrower pay off the interest and fee balances on the loan. It is important to be cognizant of timing in this case as balances can change with time.

  2. Interest and Fee Handling configuration: As part of the restructuring you will be asked to make a selection on how interest and fee balances should be handled. The options include:

    • Offset: The system will create offset transaction records for each interest and fee line item on the original loan. The offset records will be associated with the original loan. Only the principal balance of the loan will be restructured.
      In the case that you are restructuring multiple loans into one, offsets will be created against each individual loan that is being restructured.
    • Capitalize: This option capitalizes the outstanding interest and fees, adding them to the principal balance of the loan. Capitalization transactions for the interest balance and for the fee balance will be added to the original loan to increase its principal balance prior to restructuring. This allows the new balance to be restructured while providing a means for tracing back the capitalized amount to the original loan.
      Example: Assume a loan with the following outstanding balances:
      • Principal: $9,000
      • Interest: $800
      • Fees: $200
        An interest capitalization transaction would be added to this loan in the amount of $800 and a fee capitalization transaction in the amount of $200, brining the new principal balance to $10,000.
        Immediately after, the restructure would execute, closing out this loan and its balances and creating a new loan with a principal amount of $10,000.
    • Transfer: The interest and fee line items with outstanding balances are transferred to the newly restructured loan. Please note that for reporting and accounting purposes, offsets will be applied to the original loan to decrease its interest and fee balances. New interest and fee transactions will be recorded on the restructured loan in order to have these amounts apply to it. This option is useful for use cases such as making an interest rate change, in which you simply want to adjust the interest rate without otherwise impacting the loan.

Restructuring Multiple Loans into One

The restructuring endpoint facilitates the entry of one or several existing loan line item IDs. When multiple loan IDs are input, the restructuring feature aggregates all outstanding principal balances into a single new loan. Similarly, outstanding interest and fee balances are consolidated according to the selected option for handling interest and fees.

Adding Context

In addition to the configuration options, you'll notice a few properties that can be set for the purposes of enabling you to incorporate extra context for enhanced referenceability.

  1. Description: This becomes the visible name of the loan in CanopyOS, helping users identify it easily.
  2. External Fields: These fields enable the association of external data with the loan line item. For instance, you can link an ID from another system to the loan for cross-referencing purposes.
  3. Notes: Incorporating a note can be beneficial for future reference, providing insight into the reasons behind the restructuring.

After Restructuring

After a restructure has been executed, there are a few different ways you can assure awareness of the change as well as reference it in the future.

Restructure Webhook

After a restructure has been executed, a webhook notification will be sent. The webhook will contain information about the new loan line item that was created, the original loan item, and the configuration options set at the time the restructure was initiated.

For a full example of the data sent in the webhook, see our webhook documentation here.

Restructure Endpoint

If at any time after a restructure you need to reference it’s details, you can use the following restructure endpoint:

GET /accounts/{account_id}/line_items/restructures/loans/{line_item_id}

For a full example of the data returned, see our API documentation here.

Setting the include_hierarchy parameter of this call will return the full hierarchy of any loan line items that have been associated to the line item id provided as part of a restructure. This is especially useful if you are looking to understand the original loan line item id from the current loan.


The same data that can be accessed through the restructure endpoint above is also available through DataDirect as well.

The available schema and field definitions can be found in the DataDirect data dictionary here.


Restructuring a loan is a complex change and as such, there are a few important details to be aware of.

  • Within Canopy’s system, every loan restructure is considered a material change and as such, each restructure request closes out the previous loan line item and its balances and creates a new loan line item with a new line item id.
  • When a loan is restructured, its entire remaining principal is restructured over the new term. This includes any principal that is part of any form of min pay, either for the current due date or unpaid.
  • The subsequent statement following a loan's restructure is its first cycle.
  • When a loan is restructured, all of the balances included in the restructure (principal and interest/fees per the configuration options set) will be fully reamortized. This includes any past due or overpayment balloon balances. As such, if an account is in a past due/delinquent state, after a restructure, the account will be returned to a current/active state with no past due balances.
  • The same loan can be restructured multiple times, however for each restructure, the line_item_id of the currently active loan must be used, and not the on of the initial loan or any other loan line item that has already been restructured.
  • When you restructure a loan, it's a step-by-step process that doesn't happen right away. This means there might be a short wait before you see the results of the restructuring.
  • As part of the restructure, the original loan balances will be offset to bring the total balance to $0.
  • After a restructure, if the account was previously delinquent due to the original loan, the account will be reset to an active status.

Not Yet Supported

We are committed to the continual enhancement of our capabilities and are thrilled to introduce the beta version of our new restructuring endpoint along with its innovative features. Although certain functionalities are not supported at this moment, we are actively working on expanding and improving these capabilities to better serve your needs.

  1. Doing a reversal after a restructure is not currently supported.
  2. Scheduling a restructure in the time between when a statement is cut and the payment is due is not yet supported.
  3. If you are using loans on an average daily balance calculation, restructuring multiple loans into one is currently not supported.

What’s Next