Charges

Charges are objects that record financial amounts on quotes and policy transactions. Each charge has:

  • An amount, such as $42.50

  • A rate, which describes the amount per unit time

  • An optional referenceRate, described later in this topic

  • A category, such as premium or tax. Categories are defined by Socotra and aren’t extendable

  • A type, such as stampTax, or goodDriverDiscount, which is configured within the tenant

  • A tag, which is a short note that can be added using the rating plugin.

For each quote or policy transaction element, at most one charge of a given type is allowed.

During installment scheduling, each charge will be split into installment items based on the installment plan and other configured billing settings for the quote or policy.

Categories

The following charge categories are built-in, and all charges types must be configured to use one of these categories:

  • Premium

  • Tax

  • Fee

  • Surcharge

  • Discount

  • Credit

  • Nonfinancial

Charges of category Nonfinancial will not be processed for presentation on invoices, but all other charges will.

Nonfinancial charges are useful for tracking financial information that isn’t to be paid (either from insureds or to agents). For example, technical premium can be tracked as a Nonfinancial charge.

Charge Types

The allowed types for charges are configured for each tenant. Any number of charge types can be added to the system, and each will specify a category in the tenant configuration. Because of this, within each tenant, the category can be inferred from a charge type. Therefore, during pricing, the type must be returned from the rating plugin for each charge, but the category does not need to be specified.

Reference Rates

Reference rates are used for advanced pricing processes and are generally not needed for most cases.

Reference rates allow you to record a canonical rate independently of the actual rate used in price calculation. Essentially, they are a way to say, “when I want to know what the ‘real’ rate for the charge is, use this (“reference”) value. But I may manipulate this actual rate in order to coerce a desired amount to result from the price (rate times time) calculation.”

For example, Suppose you want to round every charge amount to be a whole number of dollars. For a policy that charges $100 per month but lasts 5.085 months, the amount would normally turn out to be $508.50. In this case, you can set the referenceRate to be 100, and the rate to be 99.9017 to get the desired outcome of $508.00. Alternatively, you can set the referenceRate to be 100 and the amount to $508.00, and the system will compute the rate using the amount.

Tracking the two different rates ensures you can reliably decide whether a rate should be considered to have changed during a policy transaction.

We discourage the use of reference rates except when essential cases require their use. If you don’t need them, you can ignore them.

Data Precision

Prices (i.e. the amount values for each charge) are stored with a precision based on the currency used for the quote or policy. This will be two digits of precision for most currencies.