Agency bill cycles
BillingCenter uses agency bill statements to bill producers for agency bill policies. BillingCenter manages the billing of statements using agency bill cycles.
From the perspective of Cloud API, an agency bill cycle serves as a container for information about the billing of a single statement. An agency bill cycle contains information about:
- The primary statement for that agency bill cycle. A statement is used to record the money that is due to the insurer from the producer for that agency bill period.
- The workflow of events in the agency bill cycle for that statement.
invoiceNumber
in Cloud API. This is
because in the data model, agency bill statements are a subtype of invoice.For more information on agency bill cycles, see Overview of the statement lifecycle.
You can query for agency bill cycles using Cloud API.
Query for agency bill cycles
Use the following endpoints to query for a producer’s agency bill cycles:
- GET
/billing/v1/producers/{producerId}/agency-bill-cycles
- GET
/billing/v1/producers/{producerId}/agency-bill-cycles/{agencyBillCycleId}
Most agency bill cycle information is contained in the
statementInvoice
field and the
agencyCycleProcess
field.
- The
statementInvoice
field captures information about the statement. The statement tracks the money that is due to the insurer from the producer. - The
agencyCycleProcess
captures information about the agency bill workflow for that statement, with booleans indicating whether steps in the process have been executed and dates for when those steps were executed.
The following fields in statementInvoice
are not returned by default
when retrieving a collection of agency bill cycles, but are returned when retrieving
a single agency bill cycle:
allInvoiceItemsExactlyPaid
primaryDirectBillEarned
These fields can also be returned by specifying a ?fields=*detail
or
?fields=*all
query parameter for the collection endpoint.
For example, the following call retrieves a single agency bill cycle:
Command
GET /billing/v1/producers/bc:154/agency-bill-cycles/bc:213
Response
{
"data": {
"attributes": {
"agencyCycleProcess": {
"currency": {
"code": "usd",
"name": "USD"
},
"dunning1Sent": false,
"dunning2Sent": false,
"genPastDueExceptionDate": "2025-06-30T00:00:00.000Z",
"id": "bc:SmsQ933zikf1aob-lRRFu",
"pastDueExceptionDismissed": false,
"pastDueExceptionGenerated": false,
"promiseExceptionDismissed": false,
"promiseExceptionGenerated": false,
"promiseReminderSent": false,
"sendStatementDate": "2025-05-15T00:00:00.000Z",
"statementSent": true
},
"currency": {
"code": "usd",
"name": "USD"
},
"id": "bc:213",
"statementInvoice": {
"adHoc": false,
"allInvoiceItemsExactlyPaid": false,
"amount": {
"amount": "860.00",
"currency": "usd"
},
"amountDue": {
"amount": "560.00",
"currency": "usd"
},
"eventDate": "2025-05-15",
"id": "bc:235",
"invoiceNumber": "1000000065",
"netAmount": {
"amount": "860.00",
"currency": "usd"
},
"netAmountPaid": {
"amount": "300.00",
"currency": "usd"
},
"paymentDueDate": "2025-06-29",
"primaryDirectBillEarned": {
"amount": "0.00",
"currency": "usd"
},
"status": {
"code": "billed",
"name": "Billed"
},
"subtype": "StatementInvoice"
}
},
...
}
}
In this example, the statement has been sent, but no other steps in the agency bill workflow process have been executed.
The statement has been partially paid, and provides fields for how much has been paid and how much needs to be paid for the statement to be settled.