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 as fullPay, 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 the cadence is quarterly, 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 the anchorMode to determine which date (generate, due, etc.) is being fixed.

  • dayOfWeek: For choosing the alignment for weekly or everyOtherWeek cadences.

  • weekOfMonth: For use in defining anchoring like “the 3rd Thursday of the month”, the weekOfMonth would be 3, and the dayOfWeek would be thursday.

  • 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 as monthly, quarterly, semiannually, or annually.

    • dayOfMonth is required.

    • dayOfWeek, weekOfMonth, and anchorTime must be absent.

  • weekOfMonth

    • The cadence must be month-based, such as monthly, quarterly, etc.

    • weekOfMonth and dayOfWeek must have valid non-null values. weekOfMonth may not be none.

    • dayOfMonth and anchorTime must be absent.

  • dayOfWeek

    • The cadence must be week-based, either weekly or everyOtherWeek.

    • dayOfWeek must be specified.

    • dayOfMonth, weekOfMonth, and anchorTime must be absent.

  • anchorTime

    • The anchorTime must be a valid datetime

    • dayOfMonth, dayOfWeek, and weekOfMonth must be absent.

  • none

    • dayOfMonth, dayOfWeek, weekOfMonth and anchorTime must be absent.

In addition to the anchorType rules, the system will also verify the following:

  • generateLeadDays must be an integer between 0 and 60 inclusive.

  • dueLeadDays must be an integer between 0 and generateLeadDays inclusive.

  • For each value of installmentWeights, it must be between 0.1 and 12.0 with a maximum precision of five places after the decimal. Absent weights will be inferred to be 1.

  • maxInstallmentsPerTerm must be absent or an integer equal to or greater than 1.

  • dayOfMonth must be absent or an integer from 1 to 31 inclusive.

  • dayOfWeek must be absent or one of sunday, monday, tuesday, wednesday, thursday, friday, or saturday.

  • weekOfMonth must be absent or an integer from 1 to 5 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 cadence

  • anchorMode of termStartDay

  • 14 for invoice generateLeadDays

  • 0 for dueLeadDays.

  • Even installmentWeights (all weights are 1)

  • 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.

See Also