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.

Command

GET /admin/v1/agency-bill-plans/bc:145

Response

{
    "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.

For example, the following snippet of a POST request body sets the thresholds below which statements are suppressed, with values for U.S. dollars and Japanese yen.

{
  "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.

Command

POST /admin/v1/agency-bill-plans

Request body

{
    "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 an agency bill plan using the following endpoint:

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

Use the following endpoint to delete an agency bill plan:

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.

Command

DELETE /admin/v1/agency-bill-plans/bc:146

This request returns a success message with no body.