Usage Billing

Usage billing in WHMCS allows you to set up products that contain variable-priced items that you determine pricing for at the time of invoicing based on actual usage data.

Products that use the cPanel, DirectAdmin, and Plesk modules can capture metrics. You can price and bill for these metrics or only enable them in order to capture and display use.

For example, you can use usage billing to charge for bandwidth usage, addon domains, or accounts on a reseller account. Usage billing can charge a flat rate or you can configure it to charge after a certain amount of use. You can also use flat or tiered pricing.

Module developers can implement metrics and collection routines in their provisioning modules. For more information, see our Provisioning Module documentation.

How Usage Billing Works

When a client orders a product that includes usage billing, WHMCS will track the client’s use of that metric.

For example, for a product that includes usage billing for bandwidth, at the end of each calendar month:

  1. The system will record the total consumed bandwidth.
  2. It will calculate the cost using the current pricing schema.
  3. It will add it to the service’s next renewal invoice as an individual line item.

The system will generate the service’s next renewal invoice according to the Next Due Date setting.

If you have configured metric billing for accounts that a reseller owns:

  1. WHMCS will track the number of sub-accounts that the reseller creates.
  2. On the service’s Next Due Date, the system records a snapshot of the current number of sub-accounts.
  3. The system calculates the cost according to the current pricing schema.
  4. The cost appears on the service’s next renewal invoice as an individual line item.
WHMCS takes the usage snapshot on the service’s Next Due Date. Because of this, we suggest offering the product only on the monthly billing cycle, so that you bill usage frequently.

Usage Formats

Usage can be reported in one of two formats:

  • Snapshot — The system can measure and bill for usage at any time. However, usage never resets.
    We recommend using Snapshot for products with a monthly billing cycle.
  • Time Based — The system measures use over time and resets it to 0 at the end of the billing period. Bandwidth is an example of a measurement that the system typically measures monthly and resets to 0 at the end of each month.

Configuring Usage Billing and Metrics

You can enable metrics for a product in the Module Settings tab at Configuration () > System Settings > Products/Services.

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 for a product that reports metrics.

Metric Pricing

You can configure metric pricing using any of the following pricing types:

  • Per Unit — Charge the same amount for each unit.
  • Total Volume — Charge a per-unit price for the total volume that the client uses. After you select this, enter the desired pricing in the displayed text boxes.
  • Graduated — Charge a per-unit price for the consumption range. The total charge is the sum of the range calculations. After you select this, enter the desired pricing in the displayed text boxes.

Per Unit Pricing

When you select Per Unit, the price is the per-unit cost, and all units cost the same amount.

For example, if you select Per Unit and enter 1.00, the system will charge $3.00 if a customer uses three of that item.

Total Volume Pricing

When you select Total Volume, you set multiple price brackets to define the prices for different quantity levels.

For example, if you select Total Volume and enter the pricing below, the system would charge $16.00 if a customer used eight of the item. It would charge $12.50 if the customer used 25 of the item.

Starting QuantityPrice per Database
0$2.00
10$1.00
20$0.50

Graduated Pricing

When you select Graduated, multiple price brackets define the prices for different quantity levels. Unlike Total Volume pricing, customers pay the set price for each unit.

For example, if you select Total Volume and enter the pricing below, the system would charge $16.00 if a customer used eight of the item. It would charge $31.00 if the customer used 25 of the item ($2.00 each for the first nine, $1.00 each for the next 10, and $0.50 each for the remaining six).

Starting QuantityPrice per Database
0$2.00
10$1.00
20$0.50

In the Admin Area

Services for products with metrics will display the latest available usage data collected for all metrics when viewing a service in the Admin Area, regardless of the metric state.

Viewing Product Metrics in the Client Profile

The Enabled column in the Metric Statistics section indicates whether metric billing is enabled in the product configuration.

You can manually poll for the latest values at any time by clicking Refresh Now.

In the Client Area

Clients can view usage data when they view the product details for applicable services.

Invoicing and Billing

You can enable usage billing using the Enable Metric Usage Invoicing setting in the Invoice tab at Configuration () > System Settings > General Settings.

Usage Data Collection

The TenantUsageMetrics cron task updates usage data twice each day. This task runs before the CreateInvoices cron task runs.

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

Your server’s timezone must match the WHMCS server’s timezone to prevent incorrect reporting. For more information, see System Timezone Issues.

Last modified: May 29, 2024