Working with subplans
Cloud API offers CRUD functionality 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
- 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:
|
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}
- 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.