Cancel Policy Transaction

Cancels a bound policy from a date as a CANCEL transaction, for any reason, including non-payment: the request takes a date, not a reason. The server works out the cancelled term’s premium itself: each pro rata charge drops to what it earned through the cancellation date, so a cancellation on the start date is a flat cancellation, and fully earned fees stay. Add a short-rate penalty or cancellation fee if you charge one; undo the cancellation with Reinstate Policy Transaction (reinstatePolicyTransaction).

Value door (Invoicing a policy). The policy’s invoices change only as the request says: the invoicePlan you send voids the invoices it names and creates new ones, committed with the policy version, and without one every invoice stays as it is.

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.

Omit fullTermPricingInfo and the derived pricing contract is used. Billing is never derived: state it, or the cancellation stores none.

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 cancel/reinstate 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-cancel-reinstate-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 term’s billing obligations per line item. The caller states this value, and leaving it out stores none. Stated billing must pass the receivable checksum and vocabulary checks.
• 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. invoicePlan is an invoice plan: nothing in it is defaulted or inferred. If cancellation moves the billing an invoiced policy’s invoices add up to, a plan is required; without one it is refused with 422 finv2-policy-restates-invoices. A plan may credit a line the new billing drops, such as a paid tax on a flat cancellation (Credits).

Billing. Stores the caller’s billing as stated, without scaling, restoring or carrying billing from the policy: billing you leave out stores none. To keep a billed policy’s billing, state fullTermBillingInfo, at what the cancelled term owes. Kept and new invoices must still add up to the billing, as Invoice plans explains.

The policy’s layer. A policy sits at a layer of its pricing stack, read from its pricing, its billing and its active invoices. A cancellation keeps the policy at its layer unless pricingStackLayerChange names the move it makes. Leaving out fullTermBillingInfo on a billed policy drops its billing, a move from billing to pricing. An invoicePlan that voids every active invoice moves the policy down from invoicing; one that voids every active invoice and creates none needs no billing, so a cancellation that leaves billing out and voids every unpaid invoice names pricingStackLayerChange: {"from": "invoicing", "to": "pricing"}. A move the request does not name, or a named move it does not make, returns 422 policy-pricing-stack-layer-change and saves nothing; its message names the actual move and the exact pricingStackLayerChange that would name it. Billing that owes nothing sits at both billing and invoicing.

Required permission: policy.cancel