# Retention Charges
import Image from 'next/image';
Overview [#overview]
Retention charges are additional charges applied during a cancellation transaction to adjust the final amount retained for a policy. These charges may be positive to increase the amount retained or negative to decrease the amount retained.
Common use cases include:
* **Minimum Earned Premiums** - ensuring a minimum amount is retained to cover policy issuance costs
* **Short-Rate Penalties** - retaining additional amounts as a penalty for early cancellation by the insured
* **Custom Fee or Refund Requirements** - implementing other conditional fees or refunds based on custom business rules
Retention charges are fixed-amount, non-proratable charges that are not derived from rate-based calculations, making them conceptually similar to [Flat Charges](/features/billing/flat-charges).
Retention charges are automatically created by the [Cancellation Plugin](/configuration/plugins/cancellation) during cancellation transaction pricing.
Configuration [#configuration]
Retention charges are declared like other charges in , but are distinguished by having their `handling` property set to `retention`.
This is the current charge definition specification:
Retention charges are configured with `handling: retention` and should be specified with `invoicing: next`. See this [guide](/features/billing/flat-charges) for more information on configuring `normal` or `flat` charges.
Here's a tabular depiction of the `handling` and `invoicing` combinations:
The system will return an error if you attempt to deploy `retention` charges with `invoicing: scheduled` or `invoicing: immediate`.
Retention charges can be configured with `transactionBundlingEnabled: true` to enable [transaction charge bundling](#transaction_retention_charge_bundling) during invoicing. This property will be set to `false` for all charges by default.
A configuration with `normal` and `retention` charges might look like this:
```json
"charges": {
"Premium": {
"category": "premium",
"handling": "normal",
"invoicing": "scheduled"
},
"MinimumPremium": {
"category": "premium",
"handling": "retention",
"invoicing": "next"
},
"ShortRate": {
"category": "fee",
"handling": "retention",
"invoicing": "next",
"transactionBundlingEnabled": true
}
}
```
Like normal or flat charges, any element that will be associated with a retention charge must declare that charge type in its `charges` list within configuration.
For example, a configuration allowing normal and retention charges to be associated with a `CommercialAuto` element would look like this:
```json
"elements": {
"CommercialAuto": {
"charges": [ "Premium", "MinimumPremium" ]
}
}
```
This ensures that retention charges created during cancellation can be associated correctly with the configured element.
Usage [#usage]
Retention charges are created automatically by the [Cancellation Plugin](/configuration/plugins/cancellation) during cancellation transaction pricing.
The plugin evaluates the system-generated prospective cancellation charges and can output additional retention charges that represent increases or decreases in the amount retained.
Retention Charges via Cancellation Plugin [#retention-charges-via-cancellation-plugin]
When you create retention charges through the cancellation plugin, you set the `amount` on the `RatingItem` instead of the `rate`. If you supply `rate` or `referenceRate`, these will be persisted for reference, but have no functional impact. Here's an example of a retention charge `RatingItem` being created in a cancellation method:
```java
var minPremiumRatingItem = RatingItem.builder()
.elementLocator(policy.locator())
.chargeType(ChargeType.MinimumPremium)
.amount(new BigDecimal("25.00"))
.build();
```
Retention charges are fully reversed by the policy system when a reinstatement transaction is issued, regardless of whether or not there is a gap between the cancellation and reinstatement. This will result in reversal charges being generated as part of the reinstatement charges that cancel out the retention charges.
When a cancellation transaction is explicitly reversed through the issuance of a reversal transaction, the billing system will reverse the transaction's retention charges.
Invoicing Behavior [#invoicing-behavior]
Retention charges are billed according to `invoicing: next` behavior, meaning they will be included on the next invoice containing applicable uninvoiced installments.
If there are no applicable uninvoiced installments for a retention charge, then the charge will be billed as `immediate`.
When determining applicable installments for `next` invoicing, only installments matching the retention charge's currency are considered as candidates for assignment.
The following logic is applied to determine which uninvoiced installments are applicable:
1. If [transaction charge bundling](#transaction_retention_charge_bundling) is enabled, only installments originating from the bundled cancellation or reinstatement transaction are considered
2. Else, if the charge has a `policyLocator` set, only installments associated with the policy are considered
3. Else, only installments associated with the account are considered
For `immediate` billing, a single new invoice will be created which will include all retention charges created as part of the cancellation or reinstatement transaction pricing.
Generated early invoices will include all retention charges scheduled for the next invoice when `invoiceThroughTime` is used.
Retention charges that are billed `immediate` and therefore are on their own invoice will not trigger the [autopay process](/features/billing/autopay). These invoices will need to be handled separately. New payment requests can be created for these which can be handled by the [payment execution service](/features/billing/payment-execution-service).
Transaction Charge Bundling [#transaction-charge-bundling]
By default, flat and retention charges with `next` invoicing are included on invoices regardless of which transactions the installments originate from. Transaction charge bundling provides the ability to configure charges so they are included only on invoices that bill installments originating from the associated transaction.
Charge bundling is enabled as part of charge type configuration via the `transactionBundlingEnabled` attribute. When enabled, retention charges are bundled with applicable uninvoiced installments originating from the cancellation or reinstatement transaction that resulted in their creation. If there are no remaining uninvoiced installments for the cancellation or reinstatement transaction, charges are invoiced according to default `next` invoicing behavior, as if bundling were disabled.
Bundling applies during scheduled invoice generation and invoice previews.
Retention charges generated by the Cancellation Plugin with bundling enabled will be bundled with the cancellation transaction that triggered Cancellation Plugin execution and charge generation. Similarly, reversed retention charges generated during reinstatement with bundling enabled will be bundled with the reinstatement transaction that triggered Rating Plugin execution and charge generation.
Delinquency [#delinquency]
If invoices containing only retention charges become past due, the corresponding policy will enter delinquency.
## API Reference
ChargeRef
Properties:
displayName (string) [deprecated]
category (Enum none | premium | tax | fee | credit | invoiceFee | cededPremium | nonFinancial | surcharge, required)
handling (Enum flat | normal | retention, required)
invoicing (Enum scheduled | next | immediate, required)
transactionBundlingEnabled (boolean, required)