Working with subplans

Query for subplans

Retrieve subplans using the following endpoints:

GET /commission-plans/{commissionPlanId}/commission-sub-plans
GET/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}

These endpoints can be used to retrieve both conditional subplans and default subplans.

The following retrieves a single conditional subplan:

Command

GET /admin/v1/commission-plans/bc:203/commission-sub-plans/bc:209

Response

{
    "data": {
        "attributes": {
            "allEvaluations": true,
            "allJurisdictions": true,
            "allLOBCodes": true,
            "allSegments": true,
            "allTerms": true,
            "allUWCompanies": true,
            "assignedRisk": {
                "code": "all",
                "name": "All"
            },
            "id": "bc:209",
            "name": "Untitled432",
            "payableCriteria": {
                "code": "effectivedate",
                "name": "On Effective Date"
            },
            "selectedEvaluations": [
                {
                    "code": "acceptable",
                    "name": "Acceptable"
                },
                ...
            ],
            "selectedLOBCodes": [
                {
                    "code": "WorkersComp",
                    "name": "Workers' Compensation"
                },
		   ...
            ],
            ...
        }
    }
}

Because this is a conditional subplan, the response contains all the availability criteria for the subplan, such as the selectedEvaluations array and the selectedLOBCodes array. Default subplans do not have this information.

Note that when retrieving subplans, the rates are not included in the response. They are retrieved using a child endpoint. For more information, see Subplan rates.

Create a conditional subplan

Use the following endpoint to create a conditional subplan:

POST /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans

This endpoint can only be used to create conditional subplans. The default subplan is created when the commission plan itself is created.

Availability criteria

When creating a conditional subplan, you must specify some basic features about the plan as well as availability criteria. The availability criteria are defined by the following required fields:

allJurisdictions
allTerms
allEvaluations
allUWCompanies
assignedRisk
allSegments
allLOBCodes

Depending on the boolean values of the availability criteria, additional fields may be required. These are described in the "Note" column in the table in the following section.

For some of these dependent fields, they cannot be set if the call if the corresponding boolean is true. For example, if allEvaluations is set to true, you cannot set a value for selectedEvaluations.

Required fields

The required fields for creating a conditional subplan are as follows:


Field	Type	Description	Note
`commissionSubPlanRates`	Array of objects	Each object has two required fields: `rate` and `role`. `rate` is the percent commission the producer receives when it has the given role, as a decimal. `role` is the producer role associated with that rate, as a typekey reference to the `PolicyRole` typelist.	There must be a rate for each producer role supported by the commission plan. Subplan rates are queried for and patched using different endpoints. See [(pending) working with subplan rates topic]
`payableCriteria`	Typekey reference	Defines when commission becomes payable, as a typekey reference to the `PayableCriteria` typelist.
`suspendForDelinquency`	Boolean	Whether or not to suspend commission payments for delinquent policy periods.
`name`	String	The name of the subplan.
`allJurisdictions`	Boolean	Whether the subplan is available for certain jurisdictions, such as different states in the United States.	If set to `false`, you must specify which jurisdictions are eligible using the `includedJurisdictions` field. `includedJurisdictions` is an array of typekey references to the `Jurisdiction` typelist.
`allTerms`	Boolean	Whether the subplan is eligible to be used regardless of the policy term of the affected policy.	If set to `false`, you must also include the `selectedTerms` object in the request. `selectedTerms` specifies whether a subplan can be used depending on the term of the policy period. There are five boolean values that you can specify, all with a default value of `false`. For example, if `firstRenewal` is set to `true`, that subplan is only available for the term when the policy is renewed for the first time.
`allEvaluations`	Boolean	Whether to filter accounts that could be eligible for the subplan based on the account’s business value. For more, see Evaluating an account's business value.	If set to `false`, you must also specify which account evaluations are eligible using the `selectedEvaluations` field. `selectedEvaluations` is an array of typekey references to the `AccountEvaluation` typelist.
`allUWCompanies`	Boolean	Whether all underwriting companies are eligible to use the subplan.	If set to `false`, you must also specify which underwriting companies are eligible using the `selectedUWCompanies` field. `selectedUWCompanies` is an array of typekey references to the `UWCompany` typelist.
`assignedRisk`	Typekey reference	Used to define whether accounts marked as "AssignedRisk" are eligible to use the subplan. References the `AssignedRiskRestriction` typelist.	In the base configuration, there are three possible codes: `all`, `exclude`, `only`.
`allSegments`	Boolean	Whether all customer segments are eligible to use the subplan.	If set to `false`, you must also specify which segments are eligible using the `selectedSegments` field. `selectedSegments` is an array of typekey references to the `AccountSegment` typelist.
`allLOBCodes`	Boolean	Whether all LOB codes are eligible to use the subplan.	If set to `false`, you must also specify which LOB codes are eligible using the `selectedLOBCodes` field. This field is an array of typekey references to the `LOBCode` typelist.

Subplan creation example

The following POST creates a subplan with a rate for the three base configuration producer roles. The commission is payable upon the insured being billed, and commission payments are not suspended if the policy goes delinquent. It also specifies the following availability criteria:

There are no jurisdiction, term, underwriting company, or segment-related restrictions
Policies marked as "assigned risk" are excluded
The account must have an evaluation of "good" or "excellent"
The policy must be a personal auto policy

Command

POST /admin/v1/commission-plans/bc:207/commission-sub-plans

Request body

{
    "data": {
        "attributes": {
            "commissionSubPlanRates": [
                {
                        "rate": "15",
                        "role": {
                            "code": "primary"
                        }
                    },
                    {
                        "rate": "10",
                        "role": {
                            "code": "secondary"
                        }
                    },
                    {
                        "rate": "8",
                        "role": {
                            "code": "referrer"
                        }
                    }
            ],
            "payableCriteria": {
                    "code": "billing"
                },
            "suspendForDelinquency": false,
            "name": "PA Good Eval",
            "allJurisdictions": true,
            "allTerms": true,
            "allEvaluations": false,
            "selectedEvaluations": [
                {
                    "code": "good"
                },
                {
                    "code": "excellent"
                },
            ],
            "allUWCompanies": true,
            "assignedRisk": {
                "code": "exclude"
            },
            "allSegments": true,
            "allLOBCodes": false,
            "selectedLOBCodes": [
                {
                "code": "PersonalAuto"
                }
            ]
        }
    }
}

Modify a subplan

Use the following endpoint to modify a subplan:

PATCH /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}

If the parent commission plan is not in use:

For conditional subplans, you can update most subplan functionality.
For default subplans, you can only update the payableCriteria field.

Note that the same validations apply for PATCHes as for POSTS: if you patch an availability criteria field (such as allUWCompanies) to be false, then you must also provide the dependent field (such as selectedUWCompanies). Similarly, you cannot provide a value for the dependent field if the corresponding boolean is set to true.

For example, the following request body updates a subplan so that it is only available to a single underwriting company:

Example request body

{
    "data": {
        "attributes": {
            "allUWCompanies": false,
            "selectedUWCompanies": [
                {
                    "code": "mainline"
                }
            ]
        }
    }
}

When a commission plan is in use, subplans can be created, but they cannot be modified. This means that you cannot PATCH any fields on the subplan, and you cannot add details with calls to child endpoints, such as adding commissionable charge items or section rate overrides.

You can overcome these issues using a composite request. For more, see Add a subplan to a commission plan that is in use.

Deleting subplans

Delete a subplan using the following endpoint:

DELETE /admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}

Command

DELETE /admin/v1/commission-plans/bc:207/commission-sub-plans/bc:20

A request body is not needed.

You cannot delete subplans whose parent commission plan is in use.

You cannot delete the default subplan.