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.
Querying for billing plans
Use the following endpoints to query for billing plans:
- GET
/admin/v1/billing-plans
- Retrieves information on all billing plans
- GET
/admin/v1/billing-plans/{billingPlanId}
- Retrieves information about 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
},
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
: 5draftIntervalDayCount
: 3requestIntervalDayCount
: 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:
POST /admin/v1/billing-plans
{
"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
/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. - Only the
expirationDate
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>