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"
            }
        }
    }
}