Revision as of 12:17, 21 April 2020

Usage billing in WHMCS allows you to setup products which contain variable priced items whose price is determined at the time of invoicing based on usage data provided to WHMCS.

Usage can be reported in one of two formats:

• Snapshot - where the usage can be measured and billed for at any given point in time, but for which usage never resets.
• Time Based - where the usage is measured over a given period of time and resets to 0 at the end of the billing period. Bandwidth is an example of a measurement that is typically measured by month, and resets to zero at the end of each month.

The following are some example use cases for Usage Billing:

• A hosting company charges for bandwidth usage
• A hosting company charges a fixed amount per Addon Domain that is added
• A hosting company offers a hosting package with 10GB of bandwidth included and charges $1.00 per GB used over that
• A hosting company offers reseller hosting that allows you to create 10 cPanel Accounts as standard, but charges you $0.20 per account after that

Getting Started

Products associated with capable provisioning modules can capture metrics. These metrics can be can be priced and billed or simply enabled for display purposes.

Metrics are enabled in the Module Settings tab of Product Setup. If the selected module supports metrics, the Metric Billing section will be populated with each metric it can observe.

To enable a metric for billing or display purposes, slide the toggle to On. If a metric is enabled, it will appear within the client's product details view of the client area. An admin will always see all metrics, enabled or disabled, within the admin area when viewing a service belonging to a product which reports metrics.

To configure pricing for a metric, click the "Configure Pricing" under the given metric name.

Configuring Metric Pricing

Each metric has the following attributes:

• Metric Type - A Metric Type defines how the metric is measured. This can be one of either Snapshot, Daily or Monthly.
• Metric Unit - A Metric Unit defines the unit of measurement. Common examples are Megabytes, Gigabytes, Domains, Accounts, etc...
• Pricing Scheme - The Pricing Scheme defines how pricing is calculated for a given metric. See Pricing Schemes Explained below for futher details.
• Quantity Included - This is the number of units that are included as part of the base price of the product. Charging will not commence until the usage exceeds the quantity defined here.

Pricing Schemes Explained

Metric pricing can be configured using a variety of pricing schemes.

The following information will help you determine which pricing scheme is correct for your use case.

• Per Unit: Charge the same amount per unit
• Total Volume: The per unit price is determined by the total volume consumed.
• Graduated: The per unit price is per consumption range. The total charge is the sum of the range calculations.

For the Total Volume and Graduated pricing schemes, pricing must be defined in brackets.

You can create as many different pricing brackets as you wish. Pricing brackets start immediately following the Quantity Included number.

We’ll use the same bracket information in the examples below to indicate how the price billed can vary using different schemes.

Per Unit Pricing

Per unit pricing is the simplest pricing mode we offer. Enter a cost per unit and you’re done.

In a per-unit pricing scheme, prices are defined as per-unit costs, and all units cost the same. Thus, only 1 price bracket may be defined. For example if you used Per Unit pricing for "Addon Domains" and defined a cost of $1/each/period and a customer buys 3, then a $3 charge would be added at the end of the period.

Total Volume Pricing

In the total volume pricing scheme, multiple price brackets define the prices at different quantity levels. The price per unit for all units is determined by the prevailing price for the total used quantity. An example can illustrate this the best. Say you allow your customers to use an unlimited number of MySQL Databases with a pricing structure defined as follows:

If a customer uses 8 MySQL Databases, they will pay $2 per database, for a total of $16.
If a customer uses 25 MySQL Databases, they will pay $0.50 per database, for a total of $12.50.

Graduated Pricing

In the graduated pricing scheme, multiple price brackets define the prices at different quantity levels, much like in the Total Volume scheme. However, unlike the total volume scheme, your customers will pay the defined price per unit for each allocated unit. Let's see how this changes the price a customer pays using the same pricing brackets as pictured above.

If a customer uses 8 MySQL Databases, they will pay $2 per database, for a total of $16.
If a customer uses 25 MySQL Databases, they will pay $2 per database for the first 9 databases, plus $1 per database for the next 10 databases, plus $0.50 per database for the final 6 databases, for a total of $31 (9 x $2 + 10 x $1 + 6 x $0.50).

Admin Area

Services that are associated with products which have metrics will display the latest available usage data collected for all metrics when a service is viewed within the admin area, regardless of the metric state.

The Enabled column provides an indication of whether the metric is enabled for billing at the product configuration level. A check indicates that the metric usage will be billed for periodically.

You can manually poll for the latest values at any time by clicking the "Refresh Now" button located in the bottom right of the Metric Statistics panel.

Client Area

The product details view of services in the client area provides an information panel similar to that of the one found in client's service within the admin area.

The screenshot below shows how this information appears for a product assigned to the cPanel module.

The notable difference is any disabled metrics will not appear here. Only metrics that are enabled for billing will be displayed.

Invoicing and Billing

Usage billing invoicing is globally controlled by the "Enable Metric Usage Invoicing " option found within the Invoicing tab of General Settings.

When enabled, any metrics which are enabled for billing for a given product will be billed for at the time of service renewal.

Each metric will generate a line item that reports the total usage value and a breakdown of how the billed amount has been calculated. The line item's description will vary based on the pricing scheme type, the pricing brackets, and the usage incurred. All possible descriptions are available for translation via the language file system.

Please note that only the "Bandwidth" metric type is aggregate. This means that, for example, an annual service can have 11 stored snapshots of usage and included on a renewal invoice. The other metric types, such as Disk Space, will only have a snapshot of the usage at the time that the renewal invoice is generated (the current month).

When a service is terminated this will trigger the creation of a one-time usage invoice for current snapshot metrics and unbilled usage to date. This will look similar to the standard renewal invoice, except the service is excluded.

Usage Data Collection

Usage data is updated twice a day via the TenantUsageMetrics cron task.

This task will run before the CreateInvoices routine of the daily cron.

Custom cron invocations can use the option "--TenantUsageMetrics" to fire or suppress its execution.

Extensibility

Module developers can define metrics and collection routines for metrics that are to be made available for display and usage billing by a provisioning module.

To learn more, visit the Provisioning Module developer docs at https://developers.whmcs.com/provisioning-modules/