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: 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:

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>