Agency bill disbursements

An agency bill disbursement is an object used to return money that is related to an agency bill policy to a producer. Typically, agency bill disbursements are created because a producer overpaid for a given statement.

Agency bill disbursements are created manually. In some cases, agency bill disbursements require approval in order to be paid out to the recipient. BillingCenter pays agency bill disbursements by sending money from the producer's unapplied fund to the payee.

For more information, see the Application Guide.

You can retrieve, create, modify, reject, and approve agency bill disbursements through Cloud API.

Retrieve agency bill disbursements

Use the following endpoint to retrieve all of a producer’s disbursements:
  • GET /billing/v1/producers/{producerId}/disbursements
Use the following endpoint to retrieve an individual agency bill disbursement:
  • GET /billing/v1/disbursements/{disbursementId}

These endpoints return disbursements of all statuses, whether they are pending, approved, sent, and so on.

For example, the following demonstrates retrieving all of a producer’s disbursements:

Command
GET /billing/v1/producers/bc:435/disbursements
Response
{
    "count": 4,
    "data": [
        {
            "attributes": {
                "address": "e",
                "amount": {
                    "amount": "200.00",
                    "currency": "usd"
                },
                "closeDate": "2025-03-13",
                "disbursementNumber": "1000000001",
                "dueDate": "2025-07-16",
                "id": "bc:SgyU8VjhDtR891DpClRGr",
                "mailTo": "e",
                "payTo": "e",
                "paymentInstrument": {
                    "displayName": "Responsive",
                    "id": "bc:SQ3VcrkB9gHOAr7dxempT",
                    "type": "UniversalPaymentInstrument",
                    "uri": "/billing/v1/universal-payment-instruments/bc:SQ3VcrkB9gHOAr7dxempT"
                },
                "producer": {
                    "displayName": "Red Apple Agency",
                    "id": "bc:435",
                    "type": "Producer",
                    "uri": "/billing/v1/producers/bc:435"
                },
                "reason": {
                    "code": "Overpay",
                    "name": "Overpayment"
                },
                "status": {
                    "code": "Sent",
                    "name": "Sent"
                }
            },
            ...
        }
    }
}

Create agency bill disbursements

Use the following endpoint to create an agency bill disbursement:
  • POST /billing/v1/producers/{producerId}/disbursements

The following fields are required when creating an agency bill disbursement:

Field Description Note
address The address of the recipient, as a string Required.
dueDate The date the outgoing payment is due to be created, as a datetime string Required. Cannot be in the past.
mailTo The name of the recipient, as a string Required. By default this is the same as the payTo field, but can be different.
payTo The name of the payee, as a string Required.
reason An entry in the Reason typelist (for example, Cancellation or PolicyChange) Required.
amount The amount of the disbursement, as a monetaryAmount object Required. Must not be greater than the amount in the producer’s default unapplied fund.
unappliedFundSlices The unapplied fund slices from which to allocate funds in the disbursement, as an array. Each item in the array must reference an unapplied fund slice on the producer. Optional. Only available if Enhanced Funds Tracking is enabled.
paymentInstrument The payment instrument to which the disbursement is created. Optional. Overrides the default payment instrument and any payment instrument set as part of a fund slice.

For example, the following request creates an agency bill disbursement with the minimum required fields.

Command
POST /billing/v1/producers/bc:2919/disbursements
Request body
{
    "data": {
        "attributes": {
            "address": "995 N. Wildflower Way",
            "dueDate": "2025-11-11",
            "payTo": "Allrisk Agency",
            "mailTo": "Allrisk Agency",
            "reason": {
                "code": "Overpay"
            },
            "amount": {
                "amount": "50",
                "currency": "usd"
            }
        }
    }
}

If the payment instrument is not specified, the producer’s default payment instrument is used.

Agency bill disbursements when Enhanced Funds Tracking is enabled

Note: The content in this section only applies if Enhanced Funds Tracking is enabled.

When Enhanced Funds Tracking is enabled, you can optionally specify unapplied funds slices to be used in agency bill disbursements. It is not required to directly specify unapplied fund slices, whether or not Enhanced Funds Tracking is enabled.

If funds slices are not specified in the request, BillingCenter uses customizable logic to determine which slices are selected to be used first in the disbursement, as explained in the Application Guide.

If the paymentInstrument field is set in the request, BillingCenter uses that payment instrument for the disbursement. However, if this field is not set, BillingCenter must use additional logic to determine which payment instrument to use. This is because fund slices can have different payment instruments. BillingCenter also has customizable logic to determine the proper payment instrument for a disbursement. See the Application Guide for the base configuration logic for selecting a payment instrument.

The following example demonstrates specifying two unapplied fund slices when making a disbursement to a producer. The disbursement that is created must not be greater than the amount of both slices combined.

Command

POST /billing/v1/producers/bc:2919/disbursements

Request body

{
    "data": {
        "attributes": {
            "address": "995 N. Wildflower Way",
            "dueDate": "2026-10-10",
            "payTo": "Allrisk Agency",
            "mailTo": "Allrisk Agency",
            "reason": {
                "code": "Overpay"
            },
            "amount": {
                "amount": "15",
                "currency": "usd"
            },
            "unappliedFundSlices": [
                {
                    "id": "bc:SufkzH45bg4WMyH4lvCr0"
                },
                {
                    "id": "bc:STntBv8Q2VclO9pPkeWV_"
                }
            ]
        }
    }
}