Policy Change Management

This topic describes common behavior and management of two primary policy change transactions, Endorsements and Renewals.

Note

In this topic, the word Transaction can refer to either an Endorsement or a Renewal.

The functionality described here is currently gated by a feature flag. If it is not working as you expect, enable the flag in your configuration file config.json:

{
  "timezone": "America/Los_Angeles",
  "currency": "USD",
  "features" : { "property.quotes.for.endorsements.and.renewals.enabled": true }
}

Lifecycle

Policy change transaction objects in Socotra generally follow this lifecycle:

A transaction in application state is mutable and can be updated any number of times. It can be priced without advancing to quoted state, but pricing is not persisted.

A transaction in quoted state has underwriting and pricing locked in. The payment schedule is available on the plannedInvoices property of the EndorsementResponse or RenewalResponse. It can then go on to be accepted, which means it is staged for issuance, invoices will be generated and payable, and additional documents can be generated.

After quotation, the transaction can be issued so that the policy change instructions are permanently applied to its policy. The only way to undo an issued endorsement is by issuing another endorsement to back out the changes. Renewals cannot be reversed, but the policy term can be shorted with a subsequent endorsement.

Transactions in accepted state can be invalidated, which means that their invoices and other dependent transactions (such as a quoted renewal that has pricing based on an accepted endorsement) will also be invalidated. Affected invoices will have their settlementType set to invalidated. Transactions in quoted state can also be invalidated if required. See Pricing and Invalidation, below.

Steps can be skipped when specifying an end state in the transaction create request, or using the EndorsementActionRequest or RenewalActionRequest. For example, an endorsement can be created in quoted state, or a renewal can be updated to jump from application state to accepted state. Any actions that would be taken in the intermediate states will be performed, as if the state changes were done one at a time.

In addition to the above lifecycle, transactions in application, quoted or invalidated state may be discarded by the user, so they will no longer be included when fetching the policy’s endorsements or renewals.

Note

It is possible to have multiple transactions in the quoted state, but only one transaction may be in the accepted state at any one time. When there is an accepted transaction, any quoted transactions’ pricing will be based on assuming that the accepted transaction will be issued. Socotra also prevents a quoted transaction from advancing to accepted if the in-effect scheduled invoice stream issues an invoice after the creation of the quote.

Pricing and Invalidation

Each transaction is priced based on an assumption of what the policy will look like at the time the transaction is issued. If there is an accepted transaction, then all quoted transactions will be priced based on assuming that the accepted transaction will be issued. If there is no accepted transaction, then the quoted transactions’ pricing will be based on the policy itself.

It may be necessary to invalidate an accepted transaction. If this happens, then all quoted transactions (which have pricing based on the assumption that that accepted transaction was to be issued), will now have invalid pricing. Because of this, all these quoted transactions must be invalidated as well.

It is possible to have more than one transaction quoted at a time. When one of these transactions is accepted, then the remaining quoted transactions must be invalidated because they have pricing that is not based on the newly accepted transaction.

To handle these cases, the EndorsementActionRequest and RenewalActionRequest have a conflictHandling parameter. If conflictHandling is set to block, then requests which would result in undermining other transactions’ pricing will fail. If conflictHandling is set to invalidate, then other transactions whose pricing is undermined will be automatically invalidated.

When a transaction has a paid invoice and then that transaction is invalidated, its invoice’s payment will become automatically reversed.

Warning

When one transaction is accepted, it is not possible to accept another quoted transaction because the pricing for the quoted transaction depends on the accepted transaction. The accepted transaction can be either issued (so the quoted transaction can proceed) or invalidated (and the quoted transaction will also be invalidated.)

Documents

Documents may be rendered as part of the transaction. Each document that is specified to be rendered in endorsements.json or renewals.json has a generatingEvent property, which can be set to quote or accept, and the document will be rendered at the given stage. After the transaction is issued the documents associated with it will be attached to the policy itself.

If generatingEvent is not specified, the default stage for document rendering is accept.