Premium Reporting

Overview

Some insurance policies have premium that is calculated retrospectively; that is, only after the policy term or a portion of the term is completed will the actual premium be knowable. These are often called pay as you go policies because the billing is based on actual experience during the policy term.

The Premium Reporting feature is used to handle these types of policies. Unlike standard policies, billing is based on premium reports as they are filed, and not by premiums attributed to perils. There is one invoice per premium report, generated at the time the report is issued, rather than a schedule of invoices known up front.

Note

See the Premium Reporting API Guide for technical details about the API.

Lifecycle

Premium Reports are created in draft state. While in draft state they can be updated as many times as desired. Then, when the report data is ready, the report can be issued, at which time the pricing will be calculated, and documents and invoices will be generated. Issued reports can no longer be updated.

Reports in draft state may be manually discarded. After they are issued they are no longer allowed to be discarded.

When reports have data that needs to be corrected, there are two mechanisms, called “reversal” and “replacement.” See the section Correcting Premium Reports for details.

Report Timing

Reports are submitted to cover sequential segments of time. The first report has a start time equal to the start time of the policy, and an endTimestamp that can be specified to any time after the start time and before the policy expires. The subsequent report will start at the time the previous report ends, and again can end at any time before policy expiration.

Each report has a startTimestamp and an endTimestamp. The startTimestamp is always set automatically by the system.

Because of this structure, there will never be time gaps between premium reports.

Invoices

The invoice for a premium report will be due at midnight on the day the report is issued, unless that is overridden with the invoiceDueTimestamp.

Note

No automated proration or scaling will ever be done for calculating premium report premium, fees, taxes, and commissions. The actual monetary amounts supplied will be those amounts presented on the report’s invoice.

Correcting Premium Reports

Premium reports that have already been issued may be corrected in either of two ways:

  • Reversing a premium report such that it is invalidated and its time period is no longer covered by a report. A new report can be issued at a subsequent time.

  • Replacing a premium report by creating a new report to take the place of an issued report.

When a premium report is reversed or replaced, the following actions are taken:

  • Any payment applied against its invoice is reversed.

  • The invoice itself is then settled as invalidated.

  • The premium report will take the state reversed.

The event stream will have an event for the payment reversal if there was a payment reversed.

Reversals

To reverse a premium report, no payload is required for the API. Use the reversal endpoint.

Reversed premium reports will have the optional reversedTimestamp property set.

Note

Only the last of the premium reports for a policy can be reversed. To modify earlier reports, use the Replace feature.

Replacements

To replace a premium report, pass the data required to construct its replacement using the Replace a premium report endpoint.

Replacements can be tracked with the following optional properties for the premium report:

  • replacementOfLocator: The locator of the premium report that this one replaced

  • replacedByLocator: The locator of the premium report that replaced this one

  • replacedTimestamp: The time the replacement was executed

Configuration

Premium Reporting must be configured for the product for which you wish to use premium reporting. Add the premiumReporting.json file to the product folder, alongside policy.json. An example premiumReporting.json file looks like this:

{
  "premiumReportingConfiguration": [
    {
      "reportName": "standardReport",
      "fields": [
        {
          "name": "mileage",
          "title": "Miles Traveled",
          "type": "number"
        }
      ],
      "documents": [
        {
          "displayName": "Report Acknowledgement",
          "fileName": "reportAcknowledgement.pdf",
          "templateName": "reportAcknowledgement.template.liquid"
        }
      ]
    }
  ]
}

This file says that the premium report type “standardReport” will be usable within this product, and each report will have a “mileage” field of type number which will be recorded. When reports are issued, each will include a document based on the report acknowledgement document template.

When this file is deployed with the product configuration, policies can be created to use premium reports by setting the premiumReportName in the policy create request object.

Financial Calculations

Premium, fees, taxes, and commissions are calculated using a liquid template in the /calculations/premiumReports folder within the product folder. For the report name standardReport, the file standardReport.liquid will be used to calculate financial values. The following liquid filters are used in premium reports:

  • add_premium (takes an optional string parameter to set the category of the premium)

  • add_fee (takes a fee name)

  • add_tax (takes a tax name)

  • add_commission (takes a commission recipient)

A very simple premium reporting rating Liquid file could look like this:

{% assign premReport = data.premiumReport %}
{% assign miles = premReport.field_values.mileage[0] %}
{% assign prem = miles | times: 0.015 %}
{{ prem | add_premium: "standard prem"}}
{% assign tax = prem | times: 0.1 %}
{{ tax | add_tax: "mileage tax"}}
{% assign processing_fee = miles | times: 0.008 %}
{{ processing_fee | add_fee: "processing fee", "Std Processing Fee" }}
{{ 2 | add_commission: "Zenith Insurance Brokers" }}
{% for surcharge_loc in premReport.field_values.surcharges %}
  {% assign surcharge = premReport.field_groups_by_locator[surcharge_loc] %}
  {% assign amt = surcharge.surcharge_amount[0] | plus: 0 %}
  {{ amt | add_fee: surcharge.surcharge_type[0]  }}
{% endfor %}

Note

Premium reporting policies do not use the normal configuration for premium calculations, fees, commissions, and taxes. Those files will be ignored. Instead, the premium reporting calculation files will handle all of those calculations.

Data Objects

The data object provided to Liquid for document and invoice generation and premium calculations contains:

  • data.policy and data.policyholder. These have the same schema as for existing document rendering.

  • data.premiumReport. This is data describing the premium report, and it has the same schema as PremiumReportResponse.

  • data.previousPremiumReports. A list of older premium reports, including pricing information, for the policy.

Note

  • For document generation, the full PremiumReportResponse data is included except for the documents field.

  • During premium calculations, the following fields will not be included because they will not have been calculated yet: grossPremium; grossTaxes; taxGroups; grossFees; fees; grossCommissions; commissions; invoice; and documents.

data.premiumReport

{
  "locator": string,
  "policy_locator": string,
  "display_id": string,
  "start_timestamp": long,
  "end_timestamp": long,
  "invoice_due_timestamp": long,
  "created_timestamp": long,
  "updated_timestamp": long,
  "field_values": ValuesMap
  "field_groups_by_locator": map<String, ValuesMap>,
  "gross_premium": number,
  "premiums": List<map<String, String>>,
  "gross_taxes": number,
  "tax_groups": List<map<String, String>>,
  "gross_fees": number,
  "fees": List<map<String, String>>
  "gross_commissions": number,
  "commissions": List<map<String, String>>,
  "invoice": InvoiceMap,
  "state": string
}

data.previousPremiumReports

{
  "previousPremiumReports": [premiumReport]
}

Invoicing

Each premium report will generate an invoice with the total premiums, taxes, fees, and commissions calculated by its associated calculations liquid file.

The invoice template for a premium report called myReport will be named myReport.invoice.template.liquid.

invoiceMap

{
  "locator": string,
  "display_id": string,
  "statuses": List<map<String, Object>>,
  "payments": List<map<String, Object>>,
  "documents": List<map<String, Object>>,
  "due_timestamp": long,
  "total_due": string,
  "total_due_currency": string,
  "settlement_status": string,
  "start_timestamp": long,
  "end_timestamp": long,
  "created_timestamp": long,
  "updated_timestamp": long,
  "premium_report_locator": string,
  "premium_report_name": string,
  "policy_holder_locator": string,
  "policy_locator": string
}

Note

Functionality for grace, lapse and reinstatement is not available for premium reporting based policies.