Usage-based billing
Charge for what customers use with per-product meters, priced per unit, in graduated tiers or per package, and billed after each period ends.
Some products are charged for what is used, such as API calls, bandwidth or storage, on top of or instead of a fixed price. You add meters to the product, usage is recorded against each service, and the total is billed in arrears on the renewal invoice.
Add meters to a product#
Open the product under Products and find the Metered usage card. Click Add meter for each thing you want to measure.
| Field | What it does |
|---|---|
| Key | The name used when recording usage, for example api_calls. Lowercase letters, numbers, dashes and underscores. Each meter on a product needs a unique key. |
| Name | Shown on invoices and in the client area, for example "API calls". |
| Unit label | The unit shown next to quantities, for example "calls". Blank becomes "unit". |
| Aggregation | How several records in one period combine: Sum of all records, Highest value, or Most recent value. |
| Included per period | A free allowance, taken off before pricing. |
| Pricing model | Per unit, Graduated tiers or Per package. |
| Package size | Needed for the package model. |
| Price per unit / package | One field per currency, in major units. Many decimals are allowed, for example 0.002. |
| Tiers | For graduated tiers, one tier per line. |
A product with a zero recurring price and meters still invoices its usage. Removing a meter deletes its unbilled usage, and is refused if any usage on that meter has already been invoiced.
How usage is priced#
The allowance comes off first. Only the quantity above Included per period is charged.
- Per unit: billable quantity times the price. With 250,000 calls used, 100,000 included and
0.002per call, 150,000 calls are billed at 300.00. - Graduated tiers: write each tier as
up to | price per unit | flat fee, using cumulative quantities. Leave up to blank on the last line. Each part of the usage is charged at the price of the tier it falls in, plus a tier's flat fee when usage reaches that tier. - Per package: every started package of the package size costs the price. With a package size of 1,000, 1,001 billable units are two packages.
For example, with these tiers:
1000 | 0.002
10000 | 0.0015
| 0.001
12,000 billable units cost 1,000 × 0.002, plus 9,000 × 0.0015, plus 2,000 × 0.001, which is 2.00 + 13.50 + 2.00 = 17.50.
Each meter's cost is worked out exactly and rounded once, to the currency's smallest unit, when the line is created. Tax applies to usage lines unless the product is marked tax exempt.
Recording usage#
Usage can only be recorded for Active or Suspended services, and a quantity cannot be negative.
- Staff: on the service page, the Metered usage card has a Record usage form with Meter, Quantity, an optional When and an optional Idempotency key. An idempotency key makes a repeated submission with the same key return the first record instead of adding a second. Unbilled records can be deleted from Recent records.
- REST API: your own software can post usage records with the
usage.writeability. See REST API. Each new record fires theusage.recordedwebhook event. - Server modules: a provisioning module can report usage itself, and the billing run pulls it every day. None of the bundled cPanel/WHM, DirectAdmin or Enhance modules do this at present.
The card also shows the unbilled usage for the current period with an Estimated usage charge (before tax). Customers see their own Usage this period card on the service page, with a note that usage is billed after the period ends and the estimate excludes tax.
When usage is billed#
Usage is billed in arrears. When a service's period closes, every unbilled record from before the cut-off is added to the renewal invoice as one line per meter, such as "Hosting · API calls, 1 Nov 2026 to 30 Nov 2026 (150,000 calls ...)", and marked Invoiced. Records recorded after the cut-off wait for the next invoice.
Because the whole period's usage has to be known, a metered service is invoiced on its due date, not 14 days ahead like other renewals. See Recurring billing.
Usage is also billed straight away, on its own invoice due today, when:
- a service is cancelled or terminated, for anything not yet billed;
- an immediate plan change moves the service to another product.
Meters with usage but a total of zero do not create an invoice line, though their records are still marked as billed. A meter without a price in the service's currency also bills nothing and shows "(no price)" in the estimate, so check that every currency you sell in has a price.
Services on internal accounts are never charged for usage.