Policy Change Management¶
In this topic, the word Transaction can refer to either an Endorsement or a Renewal.
Transactions 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 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.
accepted state can be invalidated, which means that their invoices and other dependant 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
invalidated state may be
discarded by the user, so they will no longer be included when fetching the policy’s endorsements or renewals.
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.
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 nessesary 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.
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 may be rendered as part of the transaction. Each document that is specified to be rendered in
renewals.json has a
generatingEvent property, which can be set to
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.
generatingEvent is not specified, the default stage for document rendering is