Working with commission plans
You can query for, create, and modify commission plans through Cloud API. You cannot delete commission plans. Note that the following endpoints manage information at the commission plan level only. There are a separate set of endpoints for managing information at the subplan level.
Querying for commission plans
- GET
/admin/v1/commission-plans
- GET
/admin/v1/commission-plans/{commissionPlanId}
The following example call retrieves a single commission plan. No commission subplan information is returned.
Command
GET /admin/v1/commission-plans/bc:206
Response
{
"data": {
"attributes": {
"allowedTiers": [
{
"code": "gold",
"name": "Gold"
},
{
"code": "silver",
"name": "Silver"
}
],
"currencies": [
{
"code": "usd",
"name": "USD"
}
],
"effectiveDate": "2024-05-30",
"id": "bc:206",
"inUse": false,
"name": "SCommPlan",
"planOrder": 15
},
...
}
}
Creating commission plans
- POST
/admin/v1/commission-plans
Every commission plan includes a default commission subplan. The default commission subplan is a subplan that is always available. It is used if there are no other subplans or if a given policy does not meet any of the other subplans' availability criteria.
When you create a commission plan, you must also create a default subplan in the body of the request. Therefore, a POST request for a commission plan creates two entities: one commission plan, and one commission subplan.
The following fields are required to create the commission plan.
Field | Type | Description |
defaultSubPlan |
Object | The default subplan for the commission plan. For the required fields in this object, see the table below. |
name |
String | The name of the commission plan. Must be unique. |
currencies |
Array of objects | The currencies the plan supports. Each object contains
a typekey reference to the Currency
typelist. |
allowedTiers |
Array of objects | Which producer tiers can use this plan. Each object
contains a typekey reference to the ProducerTier
typelist. |
effectiveDate |
Datetime string |
The date on which the commission plan is available for use. |
Fields required for creating a default subplan
The following fields are required in the defaultSubPlan
object.
Field | Type | Description |
commissionSubPlanRates |
Array of objects |
Each object has two required fields:
In the user interface, BillingCenter requires that you enter a rate for every available role. This is not enforced when creating a default subplan through Cloud API: this array can be left empty without throwing validation errors. |
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. |
Minimal post
- Has one allowed tier
- Supports one currency
- A commission rate of 15% for primary producers
- Commission is payable upon billing
- Commission payments are not suspended for delinquent policy periods
POST /admin/v1/commission-plans
Request body
{
"data": {
"attributes": {
"allowedTiers": [
{
"code": "gold"
}
],
"name": "Cloud API Commission Plan",
"currencies": [
{
"code": "usd"
}
],
"defaultSubPlan": {
"commissionSubPlanRates": [
{
"rate": "15",
"role": {
"code": "primary"
}
}
],
"payableCriteria": {
"code": "billing"
},
"suspendForDelinquency": false
},
"effectiveDate": "2024-02-02"
}
}
}
When created, new commission plans are automatically placed at the bottom of the commission plan priority list. (For information about commission plan priority, see The Priority column in Plans.)
The response object does not contain any information about the default subplan that
has been created. To GET, PATCH, or DELETE the default subplan, you must use a
designated endpoint, such as the GET
/admin/v1/commission-plans/{commissionPlanId}/commission-sub-plans{commissionSubPlanId}
endpoint. For more, see Commission subplans.
Modifying commission plans
- PATCH
/admin/v1/commission-plans/{commissionPlanId}
- Subplans cannot be modified using this endpoint.
- If you make a change to one of the arrays, the entire array is replaced by the PATCH
- You cannot specify the
inUse
property, since it is read-only
If a commission plan is in use, this means that it is associated with a producer on a policy period that is active. When the commission plan is in use:
- Plan currencies cannot be changed
- The plan name cannot be changed
- Allowed tiers cannot be removed
Example PATCH
The following PATCH updates the commission plan to have two supported currencies and a different name.
PATCH /admin/v1/commission-plans/bc:201
Request
body{
"data": {
"attributes": {
"currencies": [
{
"code": "cad"
},
{
"code": "usd"
}
],
"name": "Updated Cloud API Comm Plan"
}
}
}