Agency bill plans
An agency bill plan is a set of values associated with one or more agency bill producers. The plan determines how BillingCenter executes certain automatic processes for the agency bill process. This includes:
- When agency bill statements are billed and due
- Whether agency bill statement documents are sent to producers
- Whether promises are expected from producers
- Whether to send dunning letters for past due statements
For more information, see Agency bill plans.
You can query for, create, update, and delete agency bill plans using Cloud API.
Querying for agency bill plans
Query for agency bill plans using the following endpoints:
- GET
/admin/v1/agency-bill-plans
- GET
/admin/v1/agency-bill-plans/{agencyBillPlanId}
Example request
The following GET retrieves an agency bill plan with id bc:145
.
GET /admin/v1/agency-bill-plans/bc:145
{
"data": {
"attributes": {
"autoProcessWhenPaymentMatches": true,
"clearCommissionThresholdDefaults": {
"usd": "3.00"
},
"clearGrossThresholdDefaults": {
"usd": "5.00"
},
"clearingLogicTarget": {
"code": "payments",
"name": "Payments"
},
"createOffsetsOnBilledInvoices": false,
"currencies": [
{
"code": "usd",
"name": "USD"
}
],
"cycleCloseDayOfMonth": 15,
"cycleCloseDayOfMonthLogic": {
"code": "exact",
"name": "Exact Day"
},
"daysAfterCycleCloseToSendStmnt": 0,
"daysUntilFirstDunningSent": 0,
"daysUntilPromiseReminderSent": 10,
"daysUntilSecondDunningSent": 0,
"effectiveDate": "2024-05-10",
"exceptionForPastDueStatement": true,
"exceptionIfPromiseNotReceived": false,
"firstDunningSentIfNotPaid": false,
"id": "bc:145",
"inUse": false,
"lowCommissionCleared": true,
"lowGrossCleared": true,
"name": "Standard Agency Bill Plan",
"netThresholdForSuppressingStmtDefaults": {
"usd": "2.00"
},
"paymentExceptionsSent": true,
"paymentTermsInDays": 45,
"planOrder": 1,
"pmntSchdChngOffsetsOnBilled": false,
"producerWriteoffThresholdDefaults": {
"usd": "5.00"
},
"promiseDueInDays": 15,
"promiseExceptionsSent": false,
"reminderSentIfPromiseNotRcvd": false,
"secondDunningSentIfNotPaid": false,
"snapshotNonPastDueItems": true,
"statementSentAfterCycleClose": true,
"statementsWithLowNetSuppressed": true,
"workflowPlan": {
"code": "StdAgencyBill",
"name": "Standard Agency Bill"
}
},
"checksum": "0",
"links": {}
}
}
Creating agency bill plans
Use the following endpoint to create an agency bill plan:
- POST
/admin/v1/agency-bill-plans
The minimum required fields to create an agency bill plan are detailed in the following table.
Field | Value | Description |
currencies |
An array of currency objects |
The currencies that the plan supports. |
cycleCloseDayOfMonthLogic |
Typekey reference to DayOfMonthLogic
typelist |
Defines how the day of the month is identified for the cycle close. |
effectiveDate |
String | The effective date of the agency bill plan. |
name |
String | The name of the agency bill plan. Cannot be the same as another agency billing plan. |
lowCommissionCleared |
Boolean | Specifies whether BillingCenter automatically writes off commission differences if the difference is less than a given threshold. |
lowGrossCleared |
Boolean | Specifies whether BillingCenter automatically writes off gross differences if the difference is less than a given threshold. |
clearingLogicTarget |
Typekey reference to ClearingLogicTarget
typelist |
Identifies what lowCommissionCleared and
lowGrossCleared apply to. In the base
configuration, the options are promises ,
payments , and both . |
paymentTermsInDays |
Integer | The number of days between each statement's Billing Date and Due Date. |
promiseDueInDays |
Integer | The number of days after a statement's Billing Date (which is also the statement cycle's Close Date) to set the Promise Due Date. |
statementsWithLowNetSuppressed |
Boolean | Specifies whether BillingCenter will skip sending a statement when its balance is below a given threshold. Invoice items remain on that statement, whether the statement is sent or not. |
workflowPlan |
Typekey reference to the workflow
typelist |
The workflow type associated with the plan. This determines the events used by each workflow to process the agency bill cycles of the associated producers. |
Setting thresholds
Agency bill plans use thresholds to determine if certain events occur, such as
writing off commission differences or suppressing statements. If you are setting
thresholds on an agency bill plan through Cloud API, additional fields are required
to specify threshold amounts. These fields are required only when the corresponding
required field is set to true
.
The following table notes these threshold fields and their corresponding required fields:
Threshold field | Required when |
---|---|
clearCommissionThresholdDefaults |
lowCommissionCleared is set to
true |
clearGrossThresholdDefaults |
lowGrossCleared is set to
true |
netThresholdForSuppressingStmtDefaults |
statementsWithLowNetSuppressed is set
to true |
Thresholds are specified in maps, with a field for each supported currency and a value for the threshold amount for that currency.
{
"data": {
"attributes": {
"statementsWithLowNetSuppressed": true,
"netThresholdForSuppressingStmtDefaults": {
"usd": "2.00",
"jpy": "300"
}
...
For more information on using different currencies in agency bill plans, see Plans and multicurrency.
Example POST
The following is an example of a minimal POST to create an agency bill plan.
POST /admin/v1/agency-bill-plans
{
"data": {
"attributes": {
"clearingLogicTarget": {
"code": "payments"
},
"currencies": [
{
"code": "usd"
},
{
"code": "jpy"
}
],
"cycleCloseDayOfMonthLogic": {
"code": "nextbusinessday"
},
"effectiveDate": "2024-05-05",
"name": "Cloud API Agency Bill Plan",
"lowCommissionCleared": true,
"clearCommissionThresholdDefaults": {
"usd": "3.00",
"jpy": "400"
},
"lowGrossCleared": false,
"paymentTermsInDays": 40,
"promiseDueInDays": 19,
"statementsWithLowNetSuppressed": false,
"workflowPlan": {
"code": "LegacyAgencyBill"
}
}
}
}
Modifying agency bill plans
- PATCH
/admin/v1/agency-bill-plans/{agencyBillPlanId}
For plans that are not in use, you can PATCH fields that define agency bill plan behavior. For example, the following PATCH adds support for Canadian dollars and removes support for Japanese yen from the example POST above.
Command
PATCH /admin/v1/agency-bill-plans/bc:146
Request body
{
"data": {
"attributes": {
"currencies": [
{
"code": "usd"
},
{
"code": "cad"
}
],
"clearCommissionThresholdDefaults": {
"cad": "11.00",
"usd": "13.00"
}
}
}
}
If a plan is in use, most fields cannot be PATCHed. The only fields that can be modified
are expirationDate
and planOrder
.
Deleting agency bill plans
- DELETE
/admin/v1/agency-bill-plans/{agencyBillPlanId}
You can only delete agency bill plans that are not in use. The command does not require a request body.
DELETE /admin/v1/agency-bill-plans/bc:146
This request returns a success message with no body.