Proration Holdbacks


The Socotra Proration Plugin handles precise proration calculations, for deciding how to split coverage segments, such as before and after an endorsement. The Holdbacks feature extends this functionality to allow for additional amounts to be allocated to the pre-split period. This allows for assessing short rates, withholding fees from refund, maintaining minimum premiums, and other cases.


Holdbacks apply only to cancellations, and may not be used for endorsements. They require the use of the new cancellation functionality; legacy cancellations will result in an error if holdbacks are attempted.

Holdbacks are created in the Proration Plugin. After the pre-split pro rata amount has been calculated, a portion of the remainder (the amount allocated after the split, which in the case of a cancellation would normally be refunded) can be allocated to a holdback and retained.

For example, suppose a cancellation is issued halfway through a policy with $1000 in premium. The normal pro rata amount ($500) would be calculated and refunded. Suppose you wish to apply a 10% short-rate, and withhold $50, and only return $450. This would be done with a holdback.

On reinstatement, Socotra will automatically reverse the holdbacks for the associated cancellation so that the original premium can remain unchanged. For example, in the case above, the reinstatement premium would be $500, but the $50 holdback would be reversed, so the insured is only assessed $450 to reinstate. The total premium for the policy then remains $1000.

Plugin Coding

To create a holdback, in the ProrationResponseItem, include a non-zero amount for the holdbackAmount property. This amount may be any value from zero to the total of the post-split amount for that item.

Because cancellation may be effective prior to the effective time of a previous endorsement or other policy transaction, you may want to consider more than the post-split amount for the segment of the policy being split. Any subsequent amounts (if any) are included in the followingAmount property of the ProrationPluginItem object. For example, in a year-long policy effective January 1 2021 to January 1 2022, you may have an endorsement effective July 1 but a cancellation effective before then, on April 1. Here the segment being presented to the prorater would be the pre-endorsement segment from January to July, but you’d want to include the followingAmount premium from July to January 2022 in any short-rate calculation.

For each holdback, you can also include a note in the holdbackMetadata property for reference later. For example you could save the string 10% Short Rate for reference.


Holdbacks are only supported for the latest version of policy cancellation. Legacy cancellations do not support holdbacks.


To implement a simple holdback, change the function prorateItem in the proration simple script example to this:

function prorateItem(data, item)
  let amount = round2(parseFloat(item.amount) * getLinearFraction(data, item));
  let holdbackAmount;

  if (data.operation == 'cancellation' && item.type == 'premium')
    let remainder = item.amount - amount + (item.followingAmount | 0);
    holdbackAmount = round2(remainder * 0.1);
    holdbackAmount = 0;

  let ret = {
    proratedAmount: amount,
    holdbackAmount: holdbackAmount

  if (holdbackAmount > 0)
    ret.holdbackMetadata = '10% Short Rate!';

  return ret;

Other Details

  • The holdbacks for a given policy or transaction are returned in the PolicyPriceResponse, PolicyPriceChangeResponse, and GetPolicyPriceResponse objects, in the form of a HoldbackResponse array.

  • The segmentSplitTimestamp could be less than the segmentStartTimestamp in some cases. These are presented to the prorater to allow for creating holdbacks. (Consider a policy cancelled as of a date before the create date for a peril.) The proratedAmount must be zero in these cases but holdbacks are allowed.

  • A new FinancialTransactionResponse type of holdback has been added to reflect holdback amounts on cancellation and reinstatement invoices.

  • There are no event stream events created for holdbacks.