Add a subplan to a commission plan that is in use

Conditional subplans can be created while their parent commission plan is in use, but after they are initially created they cannot be edited.

This poses a problem for using Cloud API to create full-featured subplans on commission plans that are in use. You create the subplan in a single call, but you cannot add features like commissionable items, section rates, and incentives without additional calls. Additional calls fail because the subplan cannot be edited while the parent commission plan is in use.

To create a subplan with these features on a commission plan that is in use, you can use a composite request. Composite requests allow for multiple objects to be created in a batch that succeeds or fails as a unit. For more information, see Composite requests.

Composite requests allow you to POST a commission subplan and simultaneously POST child resources to add features to that subplan. When the composite request is executed, it commits all of the data to the database at once, avoiding the restriction on editing subplans on commission plans that are in use.

The composite request consists of an array of calls to create the subplan and any child resources. Here is the basic syntax:

{
    "requests": [
        {
            "body": {
                 <Commission subplan data>
            },
            "method": "post",
            "uri": "/admin/v1/commission-plans/<commPlanId>/commission-sub-plans",
            "vars": [
                {
                    "name": "<subplanIdentifier>",
                    "path": "$..attributes.id"
                }
            ]
        },
        {
            "body": {
		   <Subplan child resource data>
            },
            "method": "post",
            "uri": "/admin/v1/commission-plans/<commPlanId>/commission-sub-plans/${<subplanIdentifier>}/<childResource>"
        },
	...
    ]
}

In this syntax:

• The path field identifies the id of the subplan that is created. The value of this field does not need to be changed from $..attributes.id
• The name field contains an arbitrary value (with the placeholder <subplanIdentifier>) which is used to associate the subplan child resource with the id of parent subplan

For example, the following call creates a commission subplan, commissionable charge item, and a section rate on a commission plan that is in use.

Command

POST /composite/v1/composite

Request body

{
    "requests": [
        {
            "body": {
                "data": {
                    "attributes": {
                        "payableCriteria": {
                            "code": "billing"
                        },
                        "commissionSubPlanRates": [
                            {
                                "rate": "10",
                                "role": {
                                    "code": "primary"
                                }
                            },
                            {
                                "rate": "8",
                                "role": {
                                    "code": "secondary"
                                }
                            },
                            {
                                "rate": "3",
                                "role": {
                                    "code": "referrer"
                                }
                            }
                        ],
                        "suspendForDelinquency": false,
                        "name": "{{$randomAdjective}}-{{$randomBsNoun}}",
                        "allJurisdictions": true,
                        "allTerms": true,
                        "allEvaluations": true,
                        "allUWCompanies": true,
                        "assignedRisk": {
                            "code": "all"
                        },
                        "allSegments": true,
                        "allLOBCodes": true
                    }
                }
            },
            "method": "post",
            "uri": "/admin/v1/commission-plans/bc:SArRUOxjtTmzRMkl-g9Xn/commission-sub-plans",
            "vars": [
                {
                    "name": "subPlanId",
                    "path": "$..attributes.id"
                }
            ]
        },
        {
            "body": {
                "data": {
                    "attributes": {
                        "chargePattern": {
                            "id": "default_data:1"
                        }
                    }
                }
            },
            "method": "post",
            "uri": "/admin/v1/commission-plans/bc:SArRUOxjtTmzRMkl-g9Xn/commission-sub-plans/${subPlanId}/commissionable-charge-items"
        },
        {
            "body": {
                "data": {
                    "attributes": {
                        "rate": "15",
                        "sectionType": {
                            "code": "AH"
                        },
                        "role": {
                            "code": "primary"
                        }
                    }
                }
            },
            "method": "post",
            "uri": "/admin/v1/commission-plans/bc:SArRUOxjtTmzRMkl-g9Xn/commission-sub-plans/${subPlanId}/section-rates"
        }
    ]
}