# Installment Settings



Overview [#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 [#settings-list]

The following settings are supported on the <ApiLink name="InstallmentPlanRef">installment plan</ApiLink>:

* `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 <ApiLink name="InstallmentPreferences">installment preferences</ApiLink>:

* `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.

<Callout>
  The `cadence` values of *none*, *thirtyDays*, and *everyNDays* are not currently supported.
</Callout>

Resolving Settings [#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 [#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 <ApiLink name="InstallmentPreferences" /> and if the `installmentPlanName` is set there, then use that plan.
  * If not, check if the `defaultInstallmentPlan` is set on the <ApiLink name="AccountResponse">account</ApiLink>. If so, use <ApiLink name="InstallmentPlanRef">that</ApiLink>.
  * Then, check if the `defaultInstallmentPlan` is set on the <ApiLink name="ProductRef">product</ApiLink> 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 <ApiLink name="InstallmentSettings" /> for the Installment Lattice.

Quotes Example [#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-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 [#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:

```json
{
	"anchorMode": "dueTime",
	"anchorType": "dayOfMonth",
	"dayOfMonth": 10
}
```

<Callout>
  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.
</Callout>

Validation [#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 [#persistence]

After the value for each relevant setting is determined, all the settings are <ApiLink name="fetchInstallmentLatticeSettings">persisted on the installment lattice</ApiLink>.

<Callout>
  Some settings may remain `null`. For example, if `maxInstallmentsPerTerm` is null then the total number of installments will be uncapped.
</Callout>

Default Settings [#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 [#see-also]

* [Installments API](/api/billing/installments)
* [Configuration Deployments API](/api/configuration-and-development/deployments)