As the calculation vehicle for the borrower, accounts have a large computational state. Many fields and different forms of balances are calculated to represent the state of an account. Events in Canopy frequently modify the computational state of an account based on the Account Policies and the logic of the events themselves.

One event can have far-reaching, highly nuanced impacts to the computational state of an account. For example, a Payment event will reduce many calculated values: total balance of the account, interest/fee/principal balances, minimum payment obligations, payoff amounts, and more.

The computational state of an account has full immutability guarantees; Canopy is designed to reconstruct any of these values at any point in the account lifecycle. LoanLab and Preview are two simulation systems in Canopy that are designed to provide visibility into how different sequences of events impact the overall computational state of an account.

The aim of this article is to provide you with a framework to group, categorize, and reason about the computational state of an account. This framework will help you understand the implications of each decision made around Product Policies and Account Policies.

This article does not track all relevant computational fields for an account, but rather provides a framework for understanding these fields as they are encountered in the API Reference.

Account Balances

Account balances are retrievable via the Accounts API. These include total balance, as well as balances grouped by bucket (interest, fees, deferred interest, and principal). Account balances are adjusted based on any transaction activity initiated by the borrower, a servicing agent, or your systems via API request, as well as automatic transaction activity (such as interest and fee accrual).

Notably, account balances can always be constructed by looking at the line item history of an account and do not have dependencies on the borrower lifecycle. If there are no new line items on an account, the Account Balances also will not change, even if multiple cycles have passed.

Minimum Payment Obligations

Minimum Payment Obligations cover a suite of calculated values returned by Canopy's API that express information about a borrower's payment obligations for each due date. The foremost of these calculated values is the min_pay_cents value - this reflects exactly what the borrower is expected to pay before their next due date to remain in good standing. Additional calculations include various granular decompositions of min_pay_cents. For example, past-due balances are broken out into unpaid_min_pay_cents. The portion of the minimum payment driven by each balance bucket is also broken out into values like min_pay_fees_cents and min_pay_interest_cents. Finally, Canopy calculates information related to minimum payment obligations that provide important context for operators. Examples of these include cure amounts and stabilization amounts for borrowers.

Unlike account balances, minimum payment obligations have a temporal element to them. For instance, unpaid_min_pay_cents may increase after a borrower's due date has passed, if a portion of the payment obligation is not met -- even if there haven't been any new line items present on the account.

Add basic screenshots and placeholder images/diagrams and Design Team will follow up to do the formatting.

Additional Calculations

In addition to Account Balances and Minimum Payment Obligations, the computational state of an account includes an ever-growing list of useful calculations policy-driven calculations. Examples of these include Available Credit and Payoff Amount. These values are primarily found in the Accounts API and typically provide relevant context for operators. For instance, Total Payoff Amount helps answer the question: "What dollar amount would I need to pay to drive my balance down to zero?" - accounting for Deferred Interest Promotions and Interest Accrual. Available Credit is frequently used to govern authorization rules.

Computationally Dependent State

In addition to numerical calculations, certain values in Canopy -- primarily Account Statuses, have some automated behavior that is dependent on calculated values for the account. All such automated changes are documented on the Account Statuses page. For example -- Payment events that meet the full Minimum Payment Obligation automatically shift any delinquent accounts to an Active status.