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.
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.
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.
Choose values that make sense for your product and make it easy to understand the product behavior at a glance.
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.
These configurations are related to what happens when a borrower has a payment due.
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
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
You can set up various types of fees that can impact your business model. None of these fee structures are required.
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.
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.
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.
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.
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.
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.
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.
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.
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.
This defines the number of cycles of the promotional period.
Generally, we recommend the following:
|Revolving Credit||We recommend setting this to |
|Installment Loan||We recommend setting this to |
|Multi-Advance Installment||When transitions from a revolving product roll into an installment product, we recommend using the respective lengths of the revolving and installment periods|
These are two very important, interrelated parameters for revolving product constructs. They dictate how Canopy knows what minimum payments to charge during each cycle.
This indicates that Canopy will charge the
promo_min_pay_percentof the principal balance each cycle. For example passing
100respectively indicates that 100% of the borrower's principal balance will be due on the due date each cycle. Passing
50indicates that the borrower will owe 50% of their principal each cycle.
This indicates that Canopy should charge interest-only minimum payments for the borrower each cycle. For example,
100indicates that 100% of interest accrued by the borrower each cycle is owed.
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.
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.
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.
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.
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.
Currently, the only possible value for this field is
AM, as indicated in the note above.
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.
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.
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.