You are here:
InsPolicyService:cancelPolicy
Use this service to cancel an existing insurance policy.
This service works with the InsPolicyService:prepareToCancelPolicy service and with the InsPolicyRevenueScheduleService:cancelRevenueSchedule service to complete all the changes necessary to cancel a policy, provide a refund amount, and end the revenue schedule (if needed).
Method: cancelPolicy
How It Works
-
Takes the
assetIdorpolicyIdof the policy to be canceled and theeffectiveDateon which the cancellation goes into effect.
Note The effective cancellation date can't be greater than today. -
Updates the policy status to
Canceled, the original Expiration Date to the current value of the Expiration Date, and Expiration Date to a day before the Cancellation Date (with Timestamp of 11:59 PM). -
Changes the expiration date to the
effectiveDatepassed to the service with a Timestamp of 11:59 PM. -
Uses the appropriate calculation process based on the
useIsPaidFlagvalue.With
useIsPaidFlagset to false (deselected), the service prorates the policy's Total Premium For Term, Total Fee For Term, and Total Tax For Term, and calculates refunded amounts based on the Cancellation Date and Policy Paid To Date. If Policy Paid To Date is Null, the service considers the policy paid in full and uses Expiration Date.With
useIsPaidFlagset totrue(selected), the service:-
Uses payment schedule to calculate the total amount already paid for the policy. The total amount paid for the policy equals the sum of amounts in payment schedules with Is Paid set to true (selected). This amount is used in refund calculations.
-
Prorates the policy's Total Premium For Term, Total Fee For Term, and Total Tax For Term, and calculates refund amounts based on the Cancellation Date and the total amount already paid for the policy.
-
Adjusts payment schedules based on either the current date or the cancellation date, whichever is later. If payment schedules on or after this date have Is Paid set to false (deselected), the service deletes them.
-
Updates the status of all unpaid payment schedules (which are in past from
cancellationDate) toInvalid. The unpaid amount is added to the new payment schedule. -
Creates a new payment schedule for the current date with an amount equal to the refund amount already calculated and marks the status as
Valid. IfcreateTransactionis true, the service creates a cancellation transaction. -
Updates all the future policy versions with cancellation information:
-
Status: Canceled
-
Cancellation Date: The
effectiveDatepassed to the service -
Term Premium, Term Tax, and Term Fee: 0
-
Expiration Date: Day before the
effectiveDatepassed to the service with a Timestamp of 11:59 PM
-
-
-
Commits the prorated TotalPremiumForTerm to the database.
If createTransaction=true and the Id passed is assetId, creates AssetTransaction_c (Amount_c=refund, postDate_c and transactionDate_c=effectiveDate, type=transactionType (defaults to Canceled). If createTransaction=true and the Id passed is policyId, the service creates InsurancePolicyTransaction_c or InsurancePolicyTransaction (Amount_c=refund, postDate_c and transactionDate_c=effectiveDate, type=transactionType (defaults to Canceled).
The service also populates transaction breakdown data into the transaction detail object. It displays data about how much each asset, participant, and coverage contributes to the total transaction amount in terms of premium, tax, and fees. Only those assets, participants, and coverages are displayed which have at least one non-zero value for premium, tax, and fees.-
Calls InsPolicyRevenueScheduleService:cancel using the
assetIdand the newly createdtransactionId. -
The InsPolicyRevenueScheduleService: cancel service calculates the end of the revenue schedule and posts the results in the revenue schedule section of the policy. The refund amounts are from the insurance company's perspective. A negative amount results in a refund to the policyholder, and a positive amount represents an unpaid amount by the policyholder.
The service additionally supports cancellation of policies where the original policy version has a duration of less than 365 days, or less than 366 days in a leap year. See Considerations and Limitations for Insurance Policies.
Surcharges (Taxes and Fees)
This service (along with the prepareToCancel service) facilitates prorations and refunds for taxes and fees when a policy is cancelled. Here's how that works:
-
If the target policy has a
TotalTaxAmount__c, that value is prorated over the cancellation date and is set on theTotalTaxForTerm__cfield. -
If the target policy has a
TotalFeeAmount__c, that value is prorated over the cancellation date and set on theTotalFeeForTerm__cfield. -
If the
createTransactionoption (see below) is set to true and the target policy has refundableAssetPricingAdjustment__crecords, then the prorated refund amounts are set on the transaction’sTaxAmount__candFeeAmount__cfields.
If you're using the Insurance Policy object model (instead of the Asset object model), the field names are different:
-
TotalTaxAmount__c=StandardTaxAmount -
TotalTaxForTerm__c=TermTaxAmount -
TotalFeeAmount__c=StandardFeeAmount -
TotalFeeForTerm__c=TermFeeAmount -
AssetPricingAdjustment__c=InsurancePolicySurcharge -
TaxAmount__c=TransactionTaxAmount -
FeeAmount__c=TransactionFeeAmount
Want to learn about transitioning from the Asset object model to the Insurance Policy object model? Read Harmonize Insurance Policies.
Remote Options
Output JSON
If you're using the Asset object model, this service returns a JSON output node. Here's an example:
{
"output": {
"records": [
{
"instest10__TotalAmount__c": 420.97,
"instest10__TaxAmount__c": 37.93,
"instest10__FeeAmount__c": 3.68,
"instest10__Amount__c": 379.36,
"Id": "a416g0000002CZpAAM"
}
],
"totalSize": 1
}
}If you're using the Insurance Policy object model, this service returns a JSON results node. Here's an example:
{
"result": {
"type": "Cancelled",
"transactionNumber": null,
"transactionDate":
"totalAmount": null,
"taxAmount": null,
"postDate": "2021-09-01T07:00:00.000Z",
"name": "Cancelled"
"Id": null,
"feeAmount": null,
"amount": -133.4,
"additionalInfo": null
},
"error": "OK"
}