Endorse Policy Transaction

Makes a mid-term change to a bound policy (an endorsement) as an ENDORSE transaction: change coverages, limits, insureds or other field values from a date, and restate the premium and billing when the price moves. Use it when you already hold the change; to endorse through a quote, generate the draft with Generate Quote from Policy (Stateless) (generateQuote) and transactionType: ENDORSE. A cancelled policy takes no endorsement until Reinstate Policy Transaction (reinstatePolicyTransaction) brings it back.

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.

Applies an ENDORSE transaction to an existing policy. An endorsement carries one or more of five channels. The engine recomputes segments after applying every channel — adjacent segments with identical data are automatically merged — and the response includes the full resulting segment set.

A cancelled policy takes no endorsement. Cancel and reinstate only switch a policy off and on; every other change is an endorsement. A policy whose latest version carries a cancellation, whether it has taken effect or is still to come, is refused with 409 PolicyCancelled until it is reinstated. To change a policy and cancel it, endorse it and then cancel it; to reinstate it with changes, reinstate it and then endorse it.

An endorsement does not switch a policy off or on. policy.policyStatus and policy.cancellationEffectiveOnDate are owned by the platform: only Cancel Policy Transaction and Reinstate Policy Transaction change them. A delta that would change either one, directly or inside a whole-policy Overwrite, is refused with 400 SystemOwnedPolicyValue, and nothing is saved. A delta that restates the value the policy holds is accepted and dropped, so a whole policy object read and sent back still endorses; a whole-policy Overwrite that leaves them out keeps them.

A delta under a calculated field is not applied. The configuration calculates such a field (Get Policy Configuration marks it readOnly and x-calculated), so the endorsement drops the delta and still succeeds. The response lists each one in ignoredDeltas, with derivedFrom, the Policy fields the calculation reads: write those instead. A property schedule built from the policy’s exposures, for example, changes when you add an exposure to policy.exposures.

Input channel:

• deltas — changes to policy field data. Each carries its own startDate / endDate within the policy term, a path, an action (Add / Remove / Overwrite), and a value.

Amending the term. Shortening a term is a deltas write to the ROOT policy.policyEndDate (or policy.policyStartDate) stating the whole term as its window. There is no separate policy-info channel — the retired fullTermDeltas container channel was removed once the root fields became the single writable source.

Whole-term policy fields. Four ROOT paths hold values that are invariant across the policy term — policy.policyNumber, policy.policyStartDate, policy.policyEndDate and policy.previousPolicy. A delta on deltas that touches one of them (at any depth, and including an ancestor path such as a whole-policy Overwrite) must state the whole term as its window (startDate = the policy start, endDate = the policy end) or the write is rejected.

A term bound may not move outward, through either input channel and at any path depth: moving policyEndDate later or policyStartDate earlier is rejected (TermLengtheningNotSupported), because no endorsement path can create the extra days.

Date values. A deltas value written to a Date field — at any depth, including a Date nested inside a custom object or an embedded exposure — must be the canonical { date: "YYYY-MM-DD", timezone } object (the Fmv1Date schema) with both members stated. Delta values are stored exactly as sent, so this channel never converts: the retired { day, month, year, timezone } spelling is refused (400, InvalidDelta), and so is a write to a single member of a Date (policy.policyEndDate.year) — a Date is written whole.

Derived channels (additive on either input channel):

• fullTermPricingInfo — whole-object overwrite of the policy-root pricing contract. Supply pricingComponents (each {label, value, classification[, qualifier, earningSchedule]} — every component must name a live classification from your company’s classification registry); the four rollups (premium, taxes, fees, total) are computed by the platform from the components — any caller-supplied rollup value is ignored and recomputed.
• fullTermBillingInfo — whole-object overwrite of the policy-root Billing Aggregate: { lines: [{ invoiceType, lineItem, direction, amount }] }, the term’s billing obligations free of invoices, with no rollup and no classification. An endorsement that moves the price must restate these lines: a stated aggregate’s receivable lines must sum to fullTermPricingInfo.total, so moving the price without restating them is refused.
• fullTermPolicyRatingResult — whole-object overwrite of the policy-root canonical rating result (the twin of fullTermPricingInfo).
• crossSegmentRatingOutputs — element-level rating output, [{ path, value }]. Each path terminates at a crossSegmentRatingOutputs container on a list element (or the policy); value is the whole rating-output object for that host. There is no action (always an Overwrite) and no dates — the server derives each write’s range from the host’s presence across segments, so it applies cleanly to part-term hosts.

At least one channel is required. Any of deltas, fullTermPricingInfo, fullTermBillingInfo, fullTermPolicyRatingResult or crossSegmentRatingOutputs satisfies it, so an endorsement that restates only the Billing Aggregate is a legal transaction on its own.

Path syntax — predicate addressing. Index into a list by a predicate on any field: policy.exposures[id = '<uuid>'].bedCount, policy.coverages[coverageType = 'GL'].limits[name = 'occurrence']. The predicate must resolve to exactly one element wherever it is applied (throws on zero or multiple matches) — this uniqueness rule is the cross-segment identity guarantee.

Policy invoices. invoicePlan is an invoice plan: nothing in it is defaulted or inferred. Once active invoices exist, a change that moves the billing they add up to must carry a plan, so kept and new invoices add up to the new billing; without one it is refused with 422 finv2-policy-restates-invoices. The version and invoices commit atomically.

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 again, changed or unchanged. 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. An endorsement 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;
• stating billing on a policy that has none moves it from pricing to billing;
• an invoicePlan that voids every active invoice moves the policy down from invoicing, and one that gives it its first invoices moves it up to invoicing. A plan that voids every active invoice and creates none needs no billing, so one endorsement can take an invoiced policy to pricing with 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, so a change between those two needs no pricingStackLayerChange.

Required permission: policy.endorse