Usage-Based Billing
Usage-based billing (UBB) enables businesses to charge customers based on actual consumption rather than flat subscription fees. BillHive supports flexible usage-based billing that can operate as pure pay-as-you-go, fixed fee with overages, or hybrid models combining both approaches.
How It Works
Usage-based billing in BillHive follows a three-stage pipeline:
- Ingest Usage Events — Raw consumption data flows into BillHive via API, batch API, CSV import, or manual entry
- Configure Addon Pricing — Aggregation rules (event type, aggregation method, filters) are configured directly on addon prices with Per Unit or Volume pricing models
- Automatic Billing — At billing cycle end, BillHive aggregates events per addon price configuration, applies included quantities and overage rates, and generates invoice line items
Key Concepts
| Concept | Description |
|---|---|
| Usage Event | A discrete consumption action (API call, GB stored, message sent, token processed) |
| Addon Price UBB Config | Aggregation settings (event type, method, property, filters) configured on an addon price |
| Included Quantity | Baseline consumption bundled with an addon price at no extra charge |
| Overage | Consumption beyond the included quantity, billed at the addon price’s per-unit rate |
| Aggregation | The method used to combine usage events over a billing period (SUM, COUNT, MIN, MAX, AVG) |
| Usage Aggregation | A computed record storing raw, included, billable quantities and amount for a billing period |
Pricing Models
BillHive supports three usage-based pricing approaches:
- Fixed Fee + Overages — A base subscription fee includes N units; consumption beyond that is charged per unit. Example: $70/month for 40 automated tasks, then $1.50 per additional task.
- Pay-As-You-Go (PAYG) — Customers are billed only for what they use with no base fee. Example: $0.03 per character translated.
- Hybrid — Combines recurring flat fees with usage-based components in a single subscription.
Architecture
UBB configuration lives directly on addon prices (Per Unit Pricing or Volume Pricing models). There is no separate “metered feature” entity — the addon price itself defines:
- Event Type — Which usage events to aggregate (e.g.,
api_call) - Aggregation Method — How to combine events (SUM, COUNT, MIN, MAX, AVG)
- Aggregation Property — Which event property to aggregate (required for SUM/MIN/MAX/AVG)
- Filters — JSON key-value conditions to narrow the event stream
This design keeps billing configuration co-located with pricing, making it straightforward to set up and manage.
Platform Limits
| Limit | Value |
|---|---|
| Usage events per month | 100M |
| Maximum event size | 1 KB |
| Event ingestion throughput | 1,000 events/sec |
Higher limits are available upon request.
Pricing v2: Usage on the Boundary Invoice
Prices built in the rate plan builder hold usage as usage components on the rate plan price, with their own charge model, included quantity, minimum and cap.
Usage is billed in arrears, on the boundary invoice
Usage is always billed in arrears. At the period boundary one invoice carries the next period’s in-advance lines and the usage of the period that just ended. The old one-period delay is gone.
| Line on the 1 April invoice | Billed | Amount | GST 18% |
|---|---|---|---|
| Rate plan, April | In advance | ₹15.00 | ₹2.70 |
| Emails, March: 18,000 sent, 15,000 included, 3,000 × ₹0.004 | In arrears | ₹12.00 | ₹2.16 |
| Total | ₹31.86 | ₹4.86 |
- The usage rows of the closed period are marked billed with the order id, so a retry never bills them twice.
- On a cancel or expire the same lines are billed on the final bill. See Boundary Invoicing and the Final Bill.
- At purchase and in estimates a usage line shows Billed on usage with a zero amount.
- Usage is never prorated. Allowances reset every billing period.
- A plan change that takes effect now bills the closed period’s usage on the change order.
Details: Billing Timing.
Charge models for usage
Per unit, graduated, volume, stairstep and package pricing all work for usage, with a minimum and a cap. A minimum is billed even with no usage. See Charge Models. Rounding applies to the period total, not to each event.
Event charges and the charges API
A per-event fee is a priced occurrence, such as a ₹40 port-out. You report each occurrence with POST /subscriptions/{id}/charges. It becomes a pending charge and lands on the next invoice. You can also add an ad-hoc charge with a name and an amount. See One-Time and Event Fees.
Pass-through usage
Mark a usage piece Pass through at cost for costs such as SMS carrier fees. The line is rated at cost and marked on the invoice. The plan’s Charge GST on pass-through lines switch decides whether it carries GST. With 500 SMS at ₹1: ₹500 with no GST, or ₹500 plus ₹90 GST. See Pass-Through Charges.
Usage paid from credits
A usage component ticked Paid from credits is paid from the customer’s prepaid wallet when the invoice is created. Covered usage carries no GST, because GST was charged when the credits were bought. What credits do not cover is billed as overage, topped up, or blocked, depending on the zero-balance action. See Prepaid Credits and Paid from Credits on the Invoice.