Policy commissions

A policy commission is a collection of information about the commission that a producer earns on a policy period. It contains fields such as the plan used to calculate commission, the policy period, the producer code, and the commission override rate, if any.

Commission amounts (such as the commission earned or the commission paid) are also included in this resource, but they are not returned by default when querying for policy commissions using Cloud API. Commission amounts can be retrieved using query parameters.

Querying for policy commissions

Get all a producer’s policy commissions using the following endpoint:
  • GET /billing/v1/producers/{producerId}/producer-codes/{producerCodeId}/policy-commissions
Get all the policy commissions that are paid to all producers on a policy period using the following endpoint:
  • GET /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/policy-commissions
To get a single policy commission, use the following endpoint:
  • GET /billing/v1/producers/{producerId}/producer-codes/{producerCodeId}/policy-commissions/{policyCommissionId}

For example, the following call retrieves a single policy commission on a producer:

Command
GET /billing/v1/producers/bc:127/producer-codes/bc:183/policy-commissions/bc:217
Response
{
    "data": {
        "attributes": {
            "commissionSubPlan": {
                "displayName": "CondSubPlan",
                "id": "bc:SHXOiuOSIMzowZbeqTbFV",
                "type": "CommissionSubPlan",
                "uri": "/admin/v1/commission-plans/bc:SjIwWlktG0UlwcLdgF20f/commission-sub-plans/bc:SHXOiuOSIMzowZbeqTbFV"
            },
            "currency": {
                "code": "usd",
                "name": "USD"
            },
            "defaultForPolicy": true,
            "id": "bc:217",
            "policyPeriod": {
                "displayName": "cross-platform-monitor-1",
                "id": "bc:SHUqEMSoU383OrVOPNqSg",
                "type": "PolicyPeriod",
                "uri": "/billing/v1/accounts/bc:SyyGOASPQ15h-4fPRIuTp/policies/bc:Sa4DBxSa8vGdSqpJmABz6/policy-periods/bc:SHUqEMSoU383OrVOPNqSg"
            },
            "producerCode": {
                "displayName": "NewProd (Code)",
                "id": "bc:183",
                "type": "ProducerCode",
                "uri": "/billing/v1/producers/bc:127/producer-codes/bc:183"
            },
            "role": {
                "code": "primary",
                "name": "Primary"
            }
        },
         ...
        }
    }
}

Returning calculated values

By default, commission amounts are not returned when querying for policy commissions. This includes all monetary amount fields on a policy commission, like commissionEarnedRetained, commissionExpenseBalance, commissionWrittenOff, and so on. These fields are not returned by default for performance reasons. For more, see "Returning all fields" in The fields query parameter.

You can use query parameters to return these fields. For example, you can use ?fields=*all to return all these calculated fields, along with the fields that are returned by default. This works both when retrieving a collection of policy commissions and retrieving a single policy commission.

For example, the following call retrieves a single policy commission with the calculated commission amount fields.

Command
GET /billing/v1/producers/bc:128/producer-codes/bc:184/policy-commissions/bc:218?fields=*all

Response

{
    "data": {
        "attributes": {
            "commissionEarnedRetained": {
                "amount": "450.00",
                "currency": "usd"
            },
            "commissionExpenseBalance": {
                "amount": "450.00",
                "currency": "usd"
            },
            "commissionReserveBalance": {
                "amount": "0.00",
                "currency": "usd"
            },
            "commissionSettled": {
                "amount": "450.00",
                "currency": "usd"
            },
            "commissionSubPlan": {
                "displayName": "Default",
                "id": "bc:SkgUDEXzzZ0bjXDOLtz-b",
                "type": "CommissionSubPlan",
                "uri": "/admin/v1/commission-plans/bc:SArRUOxjtTmzRMkl-g9Xn/commission-sub-plans/bc:SkgUDEXzzZ0bjXDOLtz-b"
            },
            "commissionWrittenOff": {
                "amount": "0.00",
                "currency": "usd"
            },
            "currency": {
                "code": "usd",
                "name": "USD"
            },
            "defaultForPolicy": true,
            "id": "bc:218",
            "negativeCmsnAdjustmentBalance": {
                "amount": "0.00",
                "currency": "usd"
            },
            "paidCommission": {
                "amount": "450.00",
                "currency": "usd"
            },
            "policyPeriod": {
                "displayName": "Policy123-1",
                "id": "bc:SfS2SQqrf-MXsSUDuY1-E",
                "type": "PolicyPeriod",
                "uri": "/billing/v1/accounts/bc:SDaIYv7K8PNAtEXgdNztW/policies/bc:Sn3kcHTeNSja0kOrHhUy1/policy-periods/bc:SfS2SQqrf-MXsSUDuY1-E"
            },
            "positiveCmsnAdjustmentBalance": {
                "amount": "0.00",
                "currency": "usd"
            },
            "producerCode": {
                "displayName": "Cloud API Producer",
                "id": "bc:184",
                "type": "ProducerCode",
                "uri": "/billing/v1/producers/bc:128/producer-codes/bc:184"
            },
            "role": {
                "code": "primary",
                "name": "Primary"
            }
        },
        ...
    }
}