Installment Settings
Overview
The billing system receives transactions from the policy system, and with each of these it divides the charges for the transaction into installments which are then used to construct invoices. The choices about how it does this are informed by a collection of settings, which are based on configuration data and overrides for the policy.
Settings List
The following settings are supported on the installment plan:
cadence
: The frequency or pattern of installment creation, such asfullPay
,monthly
,weekly
, etc.maxInstallmentsPerTerm
: For each term, the installment count can be capped by this number. (Note: partial installments to start the term do not apply to this limit.)installmentWeights
: An array of decimal values with the relative weighting for each term. If a weight is not provided, 1 is presumed. For example, if weights for a quarterly cadence are specified as[3, 2]
, then the weights would be calculated as[3, 2, 1, 1]
. This means that the first installment would have amounts 50% more than the second, which would have amounts twice the third and fourth.generateLeadDays
: How many days in advance of the installment start time that the invoice for the installment will be automatically created.dueLeadDays
: How many days in advance of the installment start time that the invoice for the installment will become due.anchorMode
: When fixing a date to an anchor for installments (such as the 5th of the month or the second Tuesday of the month), this specifies whether it’s the term or installment start, the invoice generate date, or the due date that is fixed to that anchor.
In addition to the Plan settings above, the following Policy Specific settings are supported on installment preferences:
anchorTime
: A specific date that is used for alignment. For example, if thecadence
isquarterly
, then the anchor time could be March 22, 2024, and the date sequence for installments would be calculated from that; for example:2024-03-22
,2024-06-22
, and so on.anchorType
: Aligns the cadence to a specific date, day of month, or day of week, or a combination like the 3rd Thursday of each month.dayOfMonth
: For month-based cadences, such as monthly, quarterly, etc., this will anchor to a certain day of the month, and will use theanchorMode
to determine which date (generate, due, etc.) is being fixed.dayOfWeek
: For choosing the alignment forweekly
oreveryOtherWeek
cadences.weekOfMonth
: For use in defining anchoring like “the 3rd Thursday of the month”, theweekOfMonth
would be3
, and thedayOfWeek
would bethursday
.Settings to override the plan-specific values, such as
maxInstallmentsPerTerm
, are also supported here.
Note
The cadence
values of none, thirtyDays, and everyNDays are not currently supported.
Resolving Settings
The system will combine preferences and plans to determine the actual settings used for the policy. The process looks like this:
Start with the preferences for the quote or policy transaction. For those that aren’t specified, fill them in with any preferences stored on the account.
Then, determine which installment plan is to be used. This is the one on the quote or policy transaction if specified. Otherwise:
For quotes, look for a plan on the account, and if not found continue looking on the product, the tenant’s default, or the system default in that order.
For policy transactions, use the plan that’s already in use at transaction’s effective time.
Finally, use the plan’s settings to resolve any missing preferences.
Quotes Process
Installment plans and individual preferences on quotes resolve to a collection of installment settings for the resulting policy.
When a quote becomes billable, the system will do the following:
First, get the applicable Installment Plan:
Check the quote’s InstallmentPreferences and if the
installmentPlanName
is set there, then use that plan.If not, check if the
defaultInstallmentPlan
is set on the account. If so, use that.Then, check if the
defaultInstallmentPlan
is set on the product in configuration. If so, use that.If that’s not set, check the tenant’s
defaultInstallmentPlan
.Finally, if none of the above are used, the system will default to the built-in
Standard
installment plan.
Then, with the plan’s settings, we update preferences by replacing any that are included in the quote’s preferences. In this way, you can override what the plan specifies for that particular quote.
Each of these settings is then persisted on the InstallmentSettings for the Installment Lattice.
Quotes Example
Presume a quote is created with preferences of:
anchorType
:dayOfMonth
dayOfMonth
:20
dueLeadDays
:10
And also suppose the quote’s product
has a defaultInstallmentPlan
that looks like this:
anchorMode
:dueDay
dueLeadDays
:7
generateLeadDays
:18
Then the plan’s values will be added to preferences for the quote, and the result will be:
anchorType
:dayOfMonth
anchorMode
:dueDay
dayOfMonth
:20
dueLeadDays
:10
generateLeadDays
:18
Policy Transactions Process
Policy transactions have a different handling mechanism because for all these cases, there already exists a collection of settings that govern billing activity, and those are used as the baseline for additional changes.
To make billing changes, the transaction must have its triggerBillingChange
property set to true
. At that point, the preferences.installmentPreferences
property can be used to specify new setting values that will become effective at the same time as any other changes for the transaction (that is, the changes apply to the policy from the transaction’s effectiveTime
and after, but before that time the settings will remain as they were.)
If triggerBillingChange
is not true
, any installment preferences on the transaction will be ignored.
Account Preferences
Preferences can be stored at the account level in the account’s preferences.installmentPreferences
property. This is useful for cases where the insured wants coordination for invoicing across all their policies. For example, to make all invoices due on the 10th of the month, the installment preferences could look like:
{
"anchorMode": "dueTime",
"anchorType": "dayOfMonth",
"dayOfMonth": 10
}
Note
An upcoming feature for Account-Level Billing will extend this logic to combine installments across policies onto a single stream of invoicing, so that the insured will only be responsible for a single invoice per billing period.
Validation
Not all installment settings are compatible with one another. Incompatible settings will cause an error when trying to deploy the configuration.
The rules for the anchorType
are:
dayOfMonth
The
cadence
must be month-based, such asmonthly
,quarterly
,semiannually
, orannually
.dayOfMonth
is required.dayOfWeek
,weekOfMonth
, andanchorTime
must be absent.
weekOfMonth
The
cadence
must be month-based, such asmonthly
,quarterly
, etc.weekOfMonth
anddayOfWeek
must have valid non-null values.weekOfMonth
may not benone
.dayOfMonth
andanchorTime
must be absent.
dayOfWeek
The
cadence
must be week-based, eitherweekly
oreveryOtherWeek
.dayOfWeek
must be specified.dayOfMonth
,weekOfMonth
, andanchorTime
must be absent.
anchorTime
The
anchorTime
must be a validdatetime
dayOfMonth
,dayOfWeek
, andweekOfMonth
must be absent.
none
dayOfMonth
,dayOfWeek
,weekOfMonth
andanchorTime
must be absent.
In addition to the anchorType
rules, the system will also verify the following:
generateLeadDays
must be an integer between0
and60
inclusive.dueLeadDays
must be an integer between0
andgenerateLeadDays
inclusive.For each value of
installmentWeights
, it must be between0.1
and12.0
with a maximum precision of five places after the decimal. Absent weights will be inferred to be1
.maxInstallmentsPerTerm
must be absent or an integer equal to or greater than1
.dayOfMonth
must be absent or an integer from1
to31
inclusive.dayOfWeek
must be absent or one ofsunday
,monday
,tuesday
,wednesday
,thursday
,friday
, orsaturday
.weekOfMonth
must be absent or an integer from1
to5
inclusive.
Persistence
After the value for each relevant setting is determined, all the settings are persisted on the installment lattice.
Note
Some settings may remain null
. For example, if maxInstallmentsPerTerm
is null then the total number of installments will be uncapped.
Default Settings
The default values for settings are:
A
fullPay
cadenceanchorMode
oftermStartDay
14
for invoicegenerateLeadDays
0
fordueLeadDays
.Even
installmentWeights
(all weights are1
)Unlimited
maxInstallmentsPerTerm
.
The Standard
installment plan is built-in to the system, and uses the above default values. This plan can be configured to override the above defaults if desired.