Usage-Based Billing Lifecycle

This page describes the end-to-end lifecycle of usage-based billing in BillHive, from event ingestion through invoice generation.

Lifecycle Flow

1. Ingest Events
       |
2. Events Stored (schema-less, deduplicated)
       |
3. Billing Cycle End Triggers Workflow
       |
4. Find UBB-Configured Addon Prices for Subscription
       |
5. Aggregate Events per Addon Price (SUM/COUNT/MIN/MAX/AVG + filters)
       |
6. Apply Included Quantities & Overage Pricing
       |
7. Create Usage Addon Order Items
       |
8. Generate Invoice with Usage Line Items
       |
9. Notify Customer
       |
10. Mark Events as Processed

Detailed Steps

1. Event Ingestion (Continuous)

Throughout the billing period, usage events flow into BillHive via API, batch API, CSV import, or manual entry. Events are stored immediately and can be viewed in the Usage Events tab on the Usage page.

2. Storage & Deduplication

Events are persisted with their full properties in a schema-less format (JSONB). The system enforces uniqueness on (tenant_id, event_id) to prevent duplicate billing.

3. Mid-Cycle Usage Summary

At any point during the billing period, the Usage Summary section on the subscription detail page (within the Usages tab) shows current aggregated usage. Click Compute Now to trigger on-demand aggregation and see consumption before the invoice is generated.

The Usage Summary displays cards per addon price showing:

• Raw usage quantity
• Included quantity
• Billable (overage) quantity
• Estimated charge amount

4. Billing Cycle End

When a subscription’s billing period ends, BillHive triggers the usage billing workflow automatically as part of the subscription renewal process.

5. Compute Aggregations

For each addon price with UBB configuration (event type + aggregation method) linked to the subscription:

• Query all events matching the addon price’s event type and filters within the billing period
• Exclude events with DUPLICATE or INVALID status
• Apply the aggregation method (SUM, COUNT, MIN, MAX, AVG) to produce a raw quantity
• Store the result in the usage aggregation record for audit purposes

6. Apply Pricing Rules

For each aggregated addon price:

• Subtract the included quantity (addon price’s quantity field) to determine billable (overage) quantity
• Multiply by the overage unit price (addon price’s price field)
• Calculate the charge amount

billable_qty = max(0, raw_qty - included_qty)
charge_amount = billable_qty × overage_unit_price

7. Generate Invoice

Metered usage charges are added as line items to the subscription’s renewal invoice alongside any recurring base fees. Each UBB-configured addon price produces a separate line item showing:

• Addon name
• Raw usage quantity
• Included quantity
• Billable (overage) quantity
• Unit price
• Total charge

8. Notification & Processing

After invoice generation:

• Customer is notified of the new invoice
• Usage events for the completed billing period are marked as PROCESSED
• Aggregation results are stored for reporting and audit

Usage Aggregation Record

Each billing cycle produces an aggregation record per UBB-configured addon price per subscription:

The status field tracks the aggregation through its lifecycle: records start as COMPUTED when the aggregation is calculated during renewal, then transition to BILLED once the renewal order is created and the aggregation is linked via order_id. These records provide a complete audit trail from raw events through aggregation to invoice line items.

Subscription Lifecycle Interactions

Workflow Integration

Usage billing is not a standalone workflow — it is integrated directly into the finalize-renewal-subprocess (finalize-renewal-subprocess.bpmn), which runs as part of the subscription renewal process. The compute-usage-aggregations service task executes between addon term updates and renewal order creation, ensuring metered usage charges are included in the renewal order automatically.

Position in the Renewal Flow

Gateway_MergeAddons (after addon term updates)
       |
Compute Usage Aggregations (service task)
       |
Gateway_AutoRenew (exclusive gateway)
       |
Create Next Renewal Order (now includes metered usage items)

Process Variables

The compute-usage-aggregations task produces the following process variables, which are consumed downstream by the renewal order creation step:

How It Works

1. Gateway_MergeAddons — After all addon terms have been updated for the new billing period, the flow converges at this gateway.
2. Compute Usage Aggregations — The compute-usage-aggregations service task queries all UBB-configured addon prices for the subscription, aggregates usage events for the completed billing period, applies included quantities and overage pricing, and stores the results as process variables.
3. Gateway_AutoRenew — The exclusive gateway evaluates whether the subscription should auto-renew.
4. Create Next Renewal Order — When creating the renewal order, the task checks hasUsageAggregations. If true, it reads usageAggregationsJson and adds each aggregation as an Addon order item (with isMeteredUsage: true in options) alongside the standard recurring items.

This tight integration ensures that metered usage charges appear on the same renewal order and invoice as recurring subscription fees, providing a unified billing experience.