Agency bill suspense items

When creating an agency bill payment, you can also create a series of agency bill suspense items. Suspense items are payment items where the producer exists in BillingCenter, but the target policy, policy period, charge, or invoice item does not.

For example, a BillingCenter user might create agency bill suspense items when a producer sends a payment for a policy that is not yet bound, and thus does not yet exist in BillingCenter. BillingCenter holds the suspense item funds until they can be released and added to the producer’s unapplied fund. For more information, see the Application Guide.

You can retrieve, create, and release agency suspense items using Cloud API.

Retrieve agency bill suspense items

GET agency bill suspense items using the following endpoints:
  • GET /producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}/agency-suspense-payment-items
  • GET /producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}/agency-suspense-payment-items/{agencySuspPmntItemId}

For example, the following demonstrates GETing all agency bill suspense items associated with an agency cycle payment.

Command
GET /billing/v1/producers/bc:192/ab-money-rcvds/bc:872/agency-cycle-payments/bc:873/agency-suspense-payment-items
Response
{
    "count": 1,
    "data": [
        {
            "attributes": {
                "commissionAmountToApply": {
                    "amount": "8.00",
                    "currency": "usd"
                },
                "currency": {
                    "code": "usd",
                    "name": "USD"
                },
                "grossAmountToApply": {
                    "amount": "40.00",
                    "currency": "usd"
                },
                "id": "bc:SLpIWv3OfRhUHVz6DJi11",
                "paymentComments": "Payment for pc:9108, which is not yet bound",
                "policyNumber": "pc:9108"
            },
            ...
        }
    }
}

Not all fields are returned by default. Use the ?fields=*all query parameter to return additional fields such as status, executedDate, and releasedDate.

Create agency bill suspense items

Agency bill suspense items are created in a similar manner to distribution items in Cloud API: they are created in the call to create the agency bill payment.

When creating an agency bill payment through Cloud API, you can create agency bill suspense items or distribution items or both. Like distribution items, you can provide agency bill suspense items in the agencyCyclePayment object. Suspense items are specified in the agencySuspPmntItems array.

For each suspense item, the following fields are required:
  • grossAmountToApply - The gross amount of the suspense item
  • commissionAmountToApply - The commission amount of the suspense item
  • currency - The currency, as a typekey reference

You can also include the expected policy number using the policyNumber field, though it is not required.

The following example call demonstrates creating an agency bill payment with:
  • An agency bill suspense item of $50 gross with $5 commission
  • A distribution item of $100 gross minus $10 commission
Command
POST /billing/v1/producers/bc:192/ab-money-rcvds
Request body
{
    "data": {
        "attributes": {
            "agencyCyclePayment": {
                "agencySuspPmntItems": [
                    {
                        "commissionAmountToApply": {
                            "amount": "5.00",
                            "currency": "usd"
                        },
                        "currency": {
                            "code": "usd"
                        },
                        "grossAmountToApply": {
                            "amount": "50.00",
                            "currency": "usd"
                        },
                        "policyNumber": "bc:192843"
                    }
                ],
                "agencyPaymentItems": [
                    {
                        "invoiceItem": {
                            "id": "bc:S9bTxAYQIlSrrEzbq-8fl"
                        },
                        "commissionAmountToApply": {
                            "amount": "10.00",
                            "currency": "usd"
                        },
                        "currency": {
                            "code": "usd"
                        }, 
                        "disposition": {
                            "code": "autoexception"
                        },
                        "grossAmountToApply": {
                            "amount": "100.00",
                            "currency": "usd"
                        }
                    }
                ],
                "currency": {
                    "code": "usd"
                }
            },
            "amount": {
                "amount": "99.50",
                "currency": "usd"
            },
            "currency": {
                "code": "usd"
            },
            "paymentInstrument": {
                "id": "bc:SvIIFL6cLwCgnBuL6kNeJ"
            },
            "receivedDate": "2024-06-23"
        }
    }
}

If the request returns a 201 response, the payment, distribution, and suspense items have been created. The POST request returns information about the payment, but no information about the suspense items or distribution.

Releasing agency bill suspense items

When an agency bill suspense item is released, the net funds are moved from a suspense T-account to the producer’s unapplied fund. You can release an agency bill suspense item through Cloud API.

Use the following endpoint to release an agency bill suspense item:
  • POST /producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/agency-cycle-payments/{agencyCyclePaymentId}/agency-suspense-payment-items/{agencySuspPmntItemId}/release

No request body is needed. For example:

Command
POST /billing/v1/producers/bc:192/ab-money-rcvds/bc:872/agency-cycle-payments/bc:873/agency-suspense-payment-items/bc:874/release
Request body
<no request body>

To be released, the suspense item must have a status of Executed.