previewPolicyPremium(premiumPreviewInput, policyId)

Preview prorated and rolled-up premium amounts across a draft insurance policy hierarchy without creating or updating changes.

API Version

68.0

Requires Chatter

Signature

public static ConnectApi.PremiumPreviewRepresentation previewPolicyPremium(ConnectApi.PremiumPreviewInputRep premiumPreviewInput, String policyId)

Parameters

premiumPreviewInput: Type: ConnectApi.PremiumPreviewInputRep; Input representation of hierarchy-node references to compute. Omit or leave references empty to get only the policy-root amounts.
policyId: Type: String; ID of the insurance policy (prefix 0YT) to preview premiums for.

Return Value

Type: ConnectApi.PremiumPreviewRepresentation

Usage

Use this method when a brokerage sales or service workflow needs to preview rolled-up policy amounts for a Draft insurance policy before issue. Unlike committed lifecycle events such as issue, endorse, cancel, and renew, this method performs a read-only, in-memory calculation. It fetches the policy hierarchy, prorates and rolls up amounts, and returns the calculated amounts without updating roll-up fields, creating IPT or IPTD line items, or triggering billing.

Call this method from Apex or LWC in the same org to make an in-process Connect API call without HTTP session or remote-site configuration. For same-org automation, use this method instead of making an HTTP callout to the REST-based premium-preview resource.

Keep these behaviors in mind.

Whole-policy preview: Pass an empty PremiumPreviewInputRep, or leave the references parameter null or empty to preview the entire policy. The response contains one entry for the policy root.
Per-node preview: Provide up to 2,000 hierarchy-node IDs for policies, assets, participants, coverages, or surcharges. Results are returned in the same order as the requested references. Specify only the nodes you need to keep large-policy previews configurable.
Amounts: Each successful result includes ten double fields on amounts, covering standard and term premium, fee, tax, commission, and totals. The response doesn't include top-level total fields; read amounts from results. For surcharge nodes, only totalStandard and totalTerm may be returned.
Per-node failures: A reference record that isn’t in the hierarchy returns INVALID_API_INPUT on that result’s errors list. Other nodes still compute, and the method returns normally.
Request-level failures: Conditions such as a disabled feature gate, invalid policyId, or more than 2000 references show ConnectApi.ConnectApiException. Wrap the call in try/catch when input isn’t trusted.
Calculation Parity: For identical inputs, the returned amounts are intended to match what policy issue computes for the same node, so quoted and issued figures stay aligned.

Example

These Apex examples show how to call ConnectApi.InsuranceBrokerageFamily.previewPolicyPremium().

Whole-policy preview (no references)

Do not specify references so the API response returns a single policy-root entry in results.

1Id policyId = '0YTxx000000004rGAA';
2// Empty input ⇒ policy-level (root) amounts only.
3ConnectApi.PremiumPreviewInputRep input = new ConnectApi.PremiumPreviewInputRep();
4ConnectApi.PremiumPreviewRepresentation resp =
5    ConnectApi.InsuranceBrokerageFamily.previewPolicyPremium(input, policyId);
6
7// results.size() == 1; the single entry is the policy root.
8ConnectApi.PremiumPreviewResultRepresentation root = resp.results[0];
9System.assertEquals(policyId, root.recordId);
10System.debug('totalStandard = ' + root.amounts.totalStandard); // e.g. 2204
11System.debug('totalTerm = ' + root.amounts.totalTerm); // e.g. 2164

Specific hierarchy nodes

Pass references to return one result per node, in request order.

1Id policyId = '0YTxx000000004rGAA';
2ConnectApi.PremiumPreviewReferenceRep a1 = new ConnectApi.PremiumPreviewReferenceRep();
3a1.recordId = '0YWxx00000000CvGAI'; // Asset A1
4ConnectApi.PremiumPreviewReferenceRep p1 = new ConnectApi.PremiumPreviewReferenceRep();
5p1.recordId = '0aoxx000000004rAAA'; // Participant P1
6ConnectApi.PremiumPreviewInputRep input = new ConnectApi.PremiumPreviewInputRep();
7input.references = new List<ConnectApi.PremiumPreviewReferenceRep>{ a1, p1 };
8ConnectApi.PremiumPreviewRepresentation resp =
9    ConnectApi.InsuranceBrokerageFamily.previewPolicyPremium(input, policyId);
10
11// results[0] ⇒ A1, results[1] ⇒ P1
12for (ConnectApi.PremiumPreviewResultRepresentation r : resp.results) {
13    if (r.errors == null) {
14        System.debug(r.recordId + ' totalStandard=' + r.amounts.totalStandard);
15    } else {
16        System.debug(r.recordId + ' FAILED ' + r.errors[0].errorCode + ': ' + r.errors[0].message);
17    }
18}

Per-node failure handling

A bad references fails only its own result; the method still returns a representation.

1Id policyId = '0YTxx000000004rGAA';
2ConnectApi.PremiumPreviewReferenceRep bogus = new ConnectApi.PremiumPreviewReferenceRep();
3bogus.recordId = '1OPxx0000004C93GAE'; // not a hierarchy node
4ConnectApi.PremiumPreviewInputRep input = new ConnectApi.PremiumPreviewInputRep();
5input.references = new List<ConnectApi.PremiumPreviewReferenceRep>{ bogus };
6ConnectApi.PremiumPreviewRepresentation resp =
7    ConnectApi.InsuranceBrokerageFamily.previewPolicyPremium(input, policyId);
8
9ConnectApi.PremiumPreviewResultRepresentation r = resp.results[0];
10System.assertNotEquals(null, r.errors); // amounts == null, errors populated
11System.debug(r.errors[0].errorCode); // e.g. INVALID_API_INPUT

Insurance Developer Guide