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

Query for commission plans using the following endpoints:
  • 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

Use the following endpoint to create a commission plan:
  • 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: rate and role.

  • rate is the percent commission the producer receives when it has the given role, as an integer.
  • role is the producer role associated with that rate, as a typekey reference to the PolicyRole typelist.

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

The following is a minimal post where the commission plan has the following features:
  • Has one allowed tier
  • Supports one currency
The default subplan has the following features:
  • A commission rate of 15% for primary producers
  • Commission is payable upon billing
  • Commission payments are not suspended for delinquent policy periods
Command
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

Modify commission plans using the following endpoint:
  • PATCH /admin/v1/commission-plans/{commissionPlanId}
Note the following when modifying commission plans:
  • 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.

Command
PATCH /admin/v1/commission-plans/bc:201
Request body
{
    "data": {
        "attributes": {
            "currencies": [
                {
                    "code": "cad"
                },
                {
                    "code": "usd"
                }
            ],
            "name": "Updated Cloud API Comm Plan"
        }
    }
}