Charge pattern rates

On a subplan, you can set a different commission rate that applies only to a specific category of charge pattern and a specific producer role. For example, you might want to create a special rate for fees for 1% that applies to primary producers only.

Note: In the user interface, these are called Special Rates. Cloud API uses the term "charge pattern rates." The term "charge pattern rates" is synonymous with "special rates."

For more information, see "Special rates" in the Application Guide.

Querying for charge pattern rates

Query for charge pattern rates using the following endpoints:
  • GET /commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/charge-pattern-rates
  • GET /commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/charge-pattern-rates/{chargePatternRateId}

For example, the following call retrieves a charge pattern rate for a subplan:

Command

POST /admin/v1/commission-plans/bc:134/commission-sub-plans/bc:199/charge-pattern-rates/bc:176
Response
{
    "data": {
        "attributes": {
            "chargePattern": {
                "displayName": "Premium",
                "id": "default_data:1",
                "type": "ChargePattern",
                "uri": "/admin/v1/charge-patterns/default_data:1"
            },
            "id": "bc:176",
            "rate": "3.00",
            "role": {
                "code": "primary",
                "name": "Primary"
            }
        },
        ...
    }
}
There is a custom chargePattern filter for charge pattern rates that allows you to retrieve only rates of a certain charge pattern. Input the display name of the charge pattern to return. If there are spaces in the display name, remove them in the query parameter. For example, the following call retrieves all charge pattern rates on a subplan that have the "Premium Including Taxes" charge pattern.
GET /admin/v1/commission-plans/bc:134/commission-sub-plans/bc:199/charge-pattern-rates?filter=chargePattern:eq:PremiumIncludingTaxes

Setting charge pattern rates

Set a charge pattern rate on a commission plan using the following endpoint:
  • POST /commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/charge-pattern-rates
To set a charge pattern rate on a subplan, you must specify three fields:
  • chargePattern - The charge pattern the rate applies to, referencing a charge pattern id. (For information on accessing charge patterns in Cloud API, see Charges and charge patterns.)
  • rate - The percent commission that will be paid.
  • role - The role of the producer the rate applies to, as a typekey reference.

For example, the following call creates a commission rate of 9% for primary producers on a specific charge pattern.

Command
POST /admin/v1/commission-plans/bc:134/commission-sub-plans/bc:199/charge-pattern-rates
Request body
{
    "data": {
        "attributes": {
            "chargePattern": {
                "id": "default_data:1"
            },
            "rate": "9",
            "role": {
                "code": "primary"
            }
        }
    }
}

Modifying charge pattern rates

Use the following endpoint to modify a charge pattern rate:
  • PATCH /commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/charge-pattern-rates/{chargePatternRateId}

When modifying a charge pattern, the only field that can be modified is rate. For example:

Sample request body
{
    "data": {
        "attributes": {
            "rate": "3"
        }
    }
}

Deleting charge pattern rates

Use the following endpoint to delete a charge pattern rate:
  • DELETE /commission-plans/{commissionPlanId}/commission-sub-plans/{commissionSubPlanId}/charge-pattern-rates/{chargePatternRateId}

You cannot delete a charge pattern rate on a commission plan that is in use.