Config Tips: Products

General Configuration#

effective_at#

This is a pattern we use for all our entities to be able to keep a clean audit history. We recommend simply using the default value which backdates the product to the year 1900, so it is always older than your oldest account.

external_product_id#

Optional. Often, your origination software or your database will have its own ID for each of your products. You can pass that ID here to make it a little easier to figure out product behavior at a glance in Canopy.



Product Overview#

These are static fields about the product. They don't drive behavior in our system itself; however, they make it easier to create a more intuitive front-end experience.

product_name product_short_description product_long_description product_color#

Choose values that make sense for your product and make it easy to understand the product behavior at a glance.

product_type#

Choose the type that best describes your product. Check out the use-cases section of the Canopy homepage to learn about each of the different product types. Note: this doesn't drive any servicing logic, but it's helpful for analytics, and helps our front-end interpret what information is relevant to show to a servicing agent.



Payment Due Policies#

These configurations are related to what happens when a borrower has a payment due.

delinquent_on_n_consecutive_late_fees#

If the borrower hasn't paid their minimum balance n times in a row, their account status will automatically switch to SUSPENDED with substatus DELINQUENT. If you don't want it ever to switch automatically, simply set this value at 99999.

charge_off_on_n_consecutive_late_fees#

If the borrower hasn't paid their minimum balance n times in a row, their account status will automatically switch to CLOSED with substatus CHARGED_OFF. If you don't want it ever to switch automatically, simply set this value at 99999.



Fee Policies#

You can set up various types of fees that can impact your business model. None of these fee structures are required.

late_fee_grace#

Sometimes you don't want your borrower to have any impact when they miss a payment until after a grace period. Automatic account status changes or any late fees do not trigger until the end of the grace period. This way you can still let the borrower know when their payment is contractually due, but offer them some under-the-hood leeway on being late for payments, reducing your servicing burden.

surcharge_fee_interval default_surcharge_fee_structure#

Optional. Surcharge fees are a unique structure to charge borrowers based on transaction volume for card or revolving products. Denote a set of ranges at which various percentage fees of transaction volume are applied. For example, you may only want to charge a 1% fee for borrowers exceeding $100,000 in monthly transaction volume, but a 2% fee for borrowers in the $50,000 - $100,000 monthly range. This fee can be unique to your business model. If you are not interested in assessing this fee to borrowers, simply ignore the surcharge fee parameters entirely.



Billing Cycle Policies#

cycle_interval#

This lays out the interval of the billing cycle for borrowers. Common values are 1 month or 1 week, though in some cases you may want atypical billing cycle lengths based on your business case.

cycle_due_interval#

This parameter lets Canopy know when you want the borrower's payments to be due each cycle. Positive or negative values can be provided here, and each mean different things. If you pass a positive value, it indicates the number of days after the cycle starts after which a payment is due. For example 20 days indicates that payment due days will be due 20 days after the start of each cycle. Negative values indicate subtraction from the previous cycle. For example -4 days indicates that the borrower's payments are due 4 days prior to the start of the subsequent cycle.

first_cycle_interval#

This parameter is totally optional and is to be provided if you want the first cycle to be a different length than the remainder. In some borrower agreements, the first cycle is shorter or longer than the remaining cycles. This can also be overridden on a per-account basis; for instance, at the time of onboarding a borrower, you may set their first_cycle_interval to a unique value. It's rare that this needs to be set at the "product" level instead of in the "create_account" API call, but if you have a set first_cycle_interval for all borrowers onboarded onto a product, you can set it here. Potential use-cases are, for example, setting up each of your borrowers to have due dates on the same day of the month, or their preferred day of the month.

close_of_business_time product_time_zone#

These parameters drive when, on any given date, activity actually occurs in Canopy. For instance, on the last day of your borrower's cycle, this dictates the time their statement is actually generated. Similarly, it dictates the time their payments are due, when promotional periods end, etc.



Interest Policies#

interest_calc_time#

This parameter is deprecated and will be removed from Canopy's API per Canopy's backward's compatibility policy. Interest calculation always occurrs at the close of business in the product timezone.



Default Attributes#

default_credit_limit_cents default_late_fee_cents default_payment_reveral_fee_cents#

These parameters really only matter if all of your borrowers for a product will have the same credit limit / late fee / payment reversal fee โ€“ hey just spare you the burden of dynamically setting these values when you onboard each borrower. If you use risk-based determinants, you may simply pass values at the time of onboarding each borrower, which will override the product-level default. Fee values, of course, can be 0 if that's not part of your business model. If your product is non-revolving, we recommend setting a default credit limit of 9999999999999.



Promotional Policies#

The lifecycle of all products in Canopy is currently broken into two sections: a promotional, and a post-promotional section. At the moment, only the promotional period can be revolving, and only the post-promotional period can be an amortizing installment loan. (Note: this still allows for pure installment or revolving products by setting a zero-length or infinite-length promotional period respectively.)

In the future revolving/amortizing characteristics will be independent of whether the product is in the promotional or post-promotional period, and products will be able to flex into promotions dynamically.

promo_len#

This defines the number of cycles of the promotional period.

Generally, we recommend the following:

Product TypeRecommendation
Revolving CreditWe recommend setting this to 99999
Installment LoanWe recommend setting this to 0. The good news is, if you do that, it doesn't matter what you set for the remaining parameters in the "Promotional Policies" section.
Multi-Advance InstallmentWhen transitions from a revolving product roll into an installment product, we recommend using the respective lengths of the revolving and installment periods

promo_min_pay_type promo_min_pay_percent#

These are two very important, interrelated parameters for revolving product constructs. They dictate how Canopy knows what minimum payments to charge during each cycle.

  • PERCENT_PRINCIPAL#

    This indicates that Canopy will charge the promo_min_pay_percent of the principal balance each cycle. For example passingPERCENT_PRINCIPAL and 100 respectively indicates that 100% of the borrower's principal balance will be due on the due date each cycle. Passing PERCENT_PRINCIPAL AND 50 indicates that the borrower will owe 50% of their principal each cycle.

  • PERCENT_INTEREST#

    This indicates that Canopy should charge interest-only minimum payments for the borrower each cycle. For example, PERCENT_INTEREST and 100 indicates that 100% of interest accrued by the borrower each cycle is owed.

promo_purchase_window_len#

This is purely a static field, primarily relevant in multi-advance installment loans. This indicates to your servicing team when purchases are considered valid, but does not drive any system logic.

promo_interest_deferred#

Deferred interest in Canopy currently only applies to multi-advance product constructs where the principal balance from a promotional period is rolled into an amortizing loan. This flag indicates that: if the borrower has paid off their entire principal balance prior to the multi-advance loan amortizing, their accrued interest is waived. If not, the deferred interest is amortized along with the principal of the loan.

promo_default_interest_rate_percent#

This parameter really only matters if all of your borrowers for a product will have the same interest rate -- it just spares you the burden of dynamically setting this value when you onboard each borrower. If you use risk-based pricing, you may simply pass the interest rate at the time of onboarding each borrower, which will override the product-level default.

promo_apr_range_inclusive_lower promo_apr_range_inclusive_upper#

These are purely static parameters -- they help us display on the front-end what the APR range is for accounts enrolled in this product. Use promo_default_interest_rate_percent, or specify promo_impl_interest_rate_percent when onboarding each borrower with a Create Account call to set their specific interest rates.



Post-Promotional Policies#

As of now, post-promotional periods can only be amortizing installment loans. If there was a Promotional period, at the time of conversion to the post-promotional period, all charges will be rolled into an installment loan.

post_promo_min_pay_type#

Currently, the only possible value for this field is AM, as indicated in the note above.

post_promo_len post_promo_default_interest_rate_percent#

This parameter really only matters if all of your borrowers for a product will have the same term for their installment loan -- it just spares you the burden of dynamically setting these values when you onboard each borrower. If you use risk-based pricing, you may simply pass the post_promo_len (term) and post_promo_impl_interest_rate_percent (rate) at the time of onboarding each borrower, which will override the product-level defaults.

post_promo_am_len_range_inclusive_lower post_promo_am_len_range_inclusive_upper post_promo_apr_range_inclusive_lower post_promo_apr_range_inclusive_upper#

These are just static fields that help our front-end present a little extra information about the product. The rate and term ranges you anticipate for borrowers onboarded onto this product.



Admin#

migration_mode#

This can also be toggled via the Toggle Migration Mode endpoint. This allows you to safely migrate accounts and line items. If migration of historical data is attempted without migration_mode enabled, Canopy will prematurely attempt to process the account to the current time, generating incomplete statements, misallocating payment pouring, incorrectly assessing fees, incorrectly incurring interest, and more.