Billing plans

A billing plan is a plan associated with accounts that determines how invoices are sent, how automatic disbursements are managed, and how payment requests are created. When you create an account, you must explicitly specify a billing plan. You cannot create an account without a billing plan. For a complete description of the business functionality of billing plans, see the Application Guide.

Some functionality is common to all plans. This includes the following:

Plan order
Endpoints for plan testing
Multicurrency functionality with plans

For more information on the common functionality, see Overview of plans.

Querying for billing plans

Use the following endpoints to query for billing plans:

GET /admin/v1/billing-plans
- Retrieves all billing plans
GET /admin/v1/billing-plans/{billingPlanId}
- Retrieves the specified billing plan

For example, the following is a snippet of the response for retrieving the sample data's "Standard Mail" billing plan (bc:101):

GET /admin/v1/billing-plans/bc:101

{
    "data": {
        "attributes": {
            "aggregation": {
                "code": "charges",
                "name": "Invoice Items"
            },
            "allowModOfManDisb": true,
            "availableDisbAmtType": {
                "code": "unappliedminusauc",
                "name": "Unapplied minus under contract"
            },
            "changeDeadlineIntervalDayCount": 0,
            "createApprActForAutoDisb": true,
            "currencies": [
                {
                    "code": "usd",
                    "name": "USD"
                }
            ],
            "delayDisbursement": 2,
            "description": "Direct bill, postal invoicing",
            "disbursementOverDefaults": {
                "usd": "0.00"
            },
            "draftDayLogic": {
                "code": "exact",
                "name": "Exact Day"
            },
            "draftIntervalDayCount": 0,
            "effectiveDate": "2022-03-25",
            "id": "bc:SwmB2Rt3gPdpWN5d33gpk",
            "inUse": true,
            "invoiceFeeDefaults": {
                "usd": "0.00"
            },
            "leadTimeDayUnit": {
                "code": "calendar",
                "name": "Calendar Days"
            },
            "lowBalanceMethod": {
                "code": "carryforward",
                "name": "Carry Forward"
            },
            "lowBalanceThresholdDefaults": {
                "usd": "0.00"
            },
            "name": "Standard Mail",
            "nonResponsivePmntDueInterval": 21,
            "paymentDueDayLogic": {
                "code": "exact",
                "name": "Exact Day"
            },
            "paymentDueInterval": 21,
            "paymentReversalFeeDefaults": {
                "usd": "0.00"
            },
            "planOrder": 1,
            "requestIntervalDayCount": 0,
            "reviewDisbursementOverDefaults": {
                "usd": "1000.00"
            },
            "sendAutoDisbAwaitingApproval": false,
            "skipInstallmentFees": false,
            "statement": {
                "code": "directbill",
                "name": "Direct Bill"
            },
            "suppressLowBalInvoices": false,
            "westernMethod": false
        },

Additional filter options

Some GET endpoints that return collections have filter options that may not appear in the API definition for one reason or another. This documentation refers to them as additional filter options.

The GET /admin/v1/billing-plans endpoint has the following additional filter options:

currencies (It accepts a list of currency typecodes for use with the compareIn operator.)

Creating billing plans

Use the following endpoint to create a billing plan:

POST /admin/v1/billing-plans

Payment due intervals validation logic

Billing plans have a nonResponsivePmntDueInterval field. The value in this field must be greater than or equal to the sum of the values of the following fields:

changeDeadlineIntervalDayCount
draftIntervalDayCount
requestIntervalDayCount

For example, suppose you want to create a billing plan where the following fields are set to the following values:

changeDeadlineIntervalDayCount: 5
draftIntervalDayCount: 3
requestIntervalDayCount: 2

The sum of these values is 10. Therefore, the value of nonResponsivePmntDueInterval must be equal to or greater than 10. If it is not, BillingCenter returns a validation error and the billing plan is not created.

Minimum creation criteria

When you create a billing plan, you must specify the following values:


Field	Value	Comments
`aggregation`	A value from the `AggregationType` typelist
`allowModOfManDisb`	Boolean	This field is not shown in the base configuration user interface.
`availableDisbAmtType`	A value from the `AvailableDistAmtType` typelist
`changeDeadlineIntervalDayCount`	integer	See the previous section for additional validation logic tied to this field.
`createApprActForAutoDisb`	Boolean
`currencies`	Array of currency codes
`delayDisbursement`	integer
`draftDayLogic`	A value from the `DayOfMonthLogic` typelist
`draftIntervalDayCount`	integer	See the previous section for additional validation logic tied to this field.
`effectiveDate`	datetime
`leadTimeDayUnit`	A value from the `DayUnit` typelist
`lowBalanceMethod`	A value from the `LowBalanceMethod` typelist
`name`	string
`nonResponsivePmntDueInterval`	integer	See the previous section for additional validation logic tied to this field.
`paymentDueDayLogic`	A value from the `DayOfMonthLogic` typelist
`paymentDueInterval`	integer
`requestIntervalDayCount`	integer	See the previous section for additional validation logic tied to this field.
`sendAutoDisbAwaitingApproval`	Boolean
`skipInstallmentFees`	Boolean
`statement`	A value from the `StatementType` typelist	In the base configuration, this typelist has only one value: `directbill`.
`suppressLowBalInvoices`	Boolean
`westernMethod`	Boolean

Example of creating a billing plan

For example, the following creates a new billing plan:

Command

POST /admin/v1/billing-plans

Response payload

{
  "data": {
    "attributes": {
        "aggregation": {
          "code": "charges"
        },
        "allowModOfManDisb": false,
        "availableDisbAmtType": {
            "code": "unappliedminusbilled"
        },
        "changeDeadlineIntervalDayCount": 5,
        "createApprActForAutoDisb": true,
        "currencies": [
            {
                "code": "usd"
             }
        ],
        "delayDisbursement": 7,
        "draftDayLogic": {
            "code": "nextbusinessday"
        },
        "draftIntervalDayCount": 6,
        "effectiveDate": "2024-12-12",
        "leadTimeDayUnit": {
            "code": "business"
        },
        "lowBalanceMethod": {
            "code": "carryforward"
        },
        "name": "Cloud API Billing Plan",
        "nonResponsivePmntDueInterval": 7,
        "paymentDueDayLogic": {
            "code": "exact"
        },
        "paymentDueInterval": 7,
        "requestIntervalDayCount": 3,
        "sendAutoDisbAwaitingApproval": false,
        "skipInstallmentFees": true,
        "statement": {
            "code": "directbill"
        },
        "suppressLowBalInvoices": true,
        "westernMethod": true
    }
  }
}

Modifying billing plans

PATCHing billing plans

Use the following endpoint to PATCH an existing billing plan:

PATCH /admin/v1/billing-plans/{billingPlanId}

When a billing plan is assigned to at least one account, BillingCenter considers the plan to be in use.

When a plan is not in use:

Its inUse field is set to false.
The entire plan can be modified.

When a plan is in use:

Its inUse field is set to true.
Through Cloud API, only expirationDate and planOrder can be modified.

For example, the following changes billing plan bc:101 so that lead time is calculated in business days and the plan expires on June 6, 2025.

If the plan is not in use, the PATCH is successful.
If the plan is in use, the PATCH fails because it specifies a value that is not expirationDate.

PATCH /admin/v1/billing-plans/bc:101

{
  "data": {
    "attributes": {
        "expirationDate": "2025-06-06",
        "leadTimeDayUnit": {
            "code": "business"
        }
    }
  }
}

DELETEing billing plans

Use the following endpoint to DELETE an existing billing plan:

DELETE /billing-plans/{billingPlanId}

When a billing plan is assigned to at least one account, BillingCenter considers the plan to be in use. When a plan is in use, it cannot be deleted.

For example, the following deletes billing plan bc:101 (assuming that it is not in use).

DELETE /admin/v1/billing-plans/bc:101

<no request body>