Cancel Policy Transaction

Cancels a policy as of a given date via a CANCEL transaction. The policy must be active at the cancellation date.

cancellationDate (= the transaction effective date) is sugar the server expands into per-segment, segment-scoped deltas on framework-required fields. policyStatus flips to cancelled from the cancellation date through end of term (splitting the segment at the boundary), and a single cancellationEffectiveOnDate is recorded uniformly across the whole term — the same value on both sides of the boundary. policyStatus alone marks which side a segment is on. There is no policyEarlyTerminationDate and no status-enum machinery.

A cancel never reprices — the pricing contract is DERIVED

The server computes what the cancelled term’s pricing contract must be, per charge. Every pricing component the policy already carries stays present, keeps its label, classification, qualifier and earningSchedule, and drops to its own earned amount through the cancellation date. A charge modelled as immediately earned (earningSchedule: "immediate" — a non-refundable policy fee) therefore keeps its whole value and is untouched by the cancellation; a pro-rata charge keeps the part the term has run through. Nothing is relabelled and nothing is merged: a charge’s <classification, qualifier> pair is its identity across policy versions, and the platform’s revenue recognition and invoice binding both attribute money by it.

A bare { "cancellationDate": ... } body is the normal request, and it always succeeds. Omit fullTermPricingInfo and the derived contract is used.

If you DO send fullTermPricingInfo, it is validated against that derived contract component by component, to the exact cent:

• every component the policy already carries must be present, at exactly the derived value and with the derived earningSchedule;
• an UNRECOGNIZED <classification, qualifier> pair is an addition — money the cancellation itself creates, such as a short-rate penalty or a cancellation fee — and it MUST carry earningSchedule: "immediate", because it is recognized on the cancellation date rather than scheduled over coverage that is ending. An addition may name any live classification (including a premium one, for a short-rate penalty) and may be negative (a clawback).

Companies that tax through InsCipher. Where the company’s InsCipher lifecycle tax sourcing is enabled, the server asks InsCipher what the state actually refunds on this cancellation and appends its answer to the derived contract as additions of its own — one immediate component per corrected tax, under that tax’s classification with a reserved qualifier of the form inscipher-PC v3 (FC for a cancellation effective on the policy’s first day; a state suffix where the charge is split by state). Their values make the written total move by exactly what the state returns; the floors are untouched. A supplied fullTermPricingInfo must include them, at the derived cents, like every other derived component — which is one more reason to omit the container. If InsCipher cannot answer while tax money is at stake, the cancellation is refused (502 inscipher-tax-calculation-failed, or 422 inscipher-lifecycle-tax-unpriceable naming the gap) rather than booked on the floors alone.

Re-valuing, re-basing or dropping an existing component is rejected with a 400 naming it. To CHANGE what the policy is priced at, book an endorsement at the same effective date and then cancel: transactions sharing an effective date are applied in booking order (ascending policyVersion), so the endorsement’s figures are what the cancellation floors against. The same composition works after a reinstatement — reinstate, then endorse — to reprice the restored term going forward.

Three optional derived channels are whole-object overwrites of a policy-root full-term container — necessarily whole-term, so none carries dates nor an element-level form:

• fullTermPricingInfo — the full-term pricing contract, validated as described above.
• fullTermBillingInfo — the Billing Aggregate, the term’s billing obligations per line item. Omit it and the platform derives it, scaling the receivable lines down to the earned floor with largest-remainder cent allocation and leaving payable lines exactly as they are — commission clawback is contractual, so there is no defensible default. State it explicitly to override that; either way a stated aggregate is checked against the receivable checksum and the per-line vocabulary rules.
• fullTermPolicyRatingResult — the canonical policy-level rating result. Unvalidated and unconstrained: it is the rater’s own output, not the money the platform books.

Policy invoices. Optionally send invoicePlan, a fully explicit keep/void/create plan. Nothing is defaulted or inferred. If cancellation moves a billed policy’s pricing target, a conserving plan is required.

Required permission: policy.cancel