Fees

Fees are additional non-premium charges that can be added to the cost of the policy. There are three types of fees:

• Standard fees, which are calculated at policy finalization and renewal only: unlike premiums and commissions, these are not recalculated for endorsements (though they can be rescaled when the policy term is reduced; see note below). These are created using the policy.calculations.liquid file and require the use of the add_fee filter.

• Ad hoc fees that can be created at any time, and are not tied to a policy transaction. These are to be calculated outside Socotra and created with an explicit API call.

• Installment fees that can be added to invoices at the time of their generation. After being generated, they are similar to ad hoc fees. See the Installment Fees feature guide for more on these.

Fees are stored at the policy level, and so (unlike premiums, taxes, and commissions) are not broken down at the peril level. The fees on an invoice can be referenced via that invoice’s Financial Transactions.

In the configuration files, The policy directory contains a file called fees.json that enumerates all fees applicable to a policy, as well as their display names. Each standard or ad hoc fee must be based on one of the types defined.

Proration

Each fee type has an optional property called proration in the fee definition. The proration property can take the value proratable or flat. If the value is proratable, then on cancellation or policy reduction the fee will be prorated if the cancellation effective date is between the start and end timestamps for the fee. If not, or if the proration property is set to flat, the fee will not be adjusted.

If proration is not specified, the default is proratable.

Note

Though fee amounts may be decreased due to cancellation or term reduction, they will not be increased if the term length is increased via an endorsement.

Note

If a policy is cancelled, fees that have a start timestamp on or after the cancellation effective timestamp will be reversed. To prevent this, when creating the fee, set the fee start timestamp to equal the policy start timestamp. Employ holdbacks to retain fees for “flat cancellations” effective at policy start.

Standard Fees

Any data on the policy or associated policyholder may be used to calculate standard fees.

Data for Standard Fee Calculation

The file policy.calculations.liquid, like other liquid calculations in Socotra, has access to an object called data, which includes information about the policy and the policyholder, and for renewals, information about the renewal.

{
  "policyholder": {...},
  "policy": {...},
  "renewal": {
    "start_timestamp": long,
    "end_timestamp": long,
    "policy_modification_locator": string
  }
}

Note

Gross premium and similar numbers on the data.policy object are the totals across all coverage terms, not just the renewal term.

Example fees.json File

{
  "fees":
  [
    {
      "name": "underwriting",
      "displayName": "Underwriting Fee"
    },
    {
      "name": "transaction",
      "displayName": "Transaction Fee"
    }
  ]
}

Example policy.calculations.liquid File

{% assign policy_char = data.policy.characteristics[0] %}

{% unless data.renewal %}
  {{ policy_char.gross_premium | times: 0.03 | add_fee: "transaction", "3% Transaction fee" }}
  {{ 10 | add_fee: "underwriting", "Underwriting fee" }}
{% else %}
  {{ 100 | add_fee: "transaction", "$100 Renewal fee" }}
{% endunless %}

The description parameter is optional, so the following would also work:

{{ 10 | add_fee: "underwriting" }}

Ad Hoc Fees

Ad hoc fees are a way of creating (and reversing) fees at any time without being tied to any Socotra transaction (like policy issuance or endorsement). Through the API you can pass in an array of fee creation requests to create the fees, and/or an array of locators (strings) of existing fees that are to be reversed.

Ad hoc fees and fee reversals will be billed on a standalone invoice, separate from the normal payment schedule.

Installment Fees

See the Installment Fees topic for more information about installment fees.