Addon Price UBB Configuration

In BillHive, usage-based billing configuration lives directly on addon prices with Per Unit Pricing or Volume Pricing models. There is no separate “metered feature” entity — the addon price itself defines how usage events are aggregated and billed.

Why Addon Price?

The addon price is the natural home for UBB configuration because:

• Pricing model (Per Unit, Volume) is defined at the addon price level
• Price, quantity (included units), and currency are already on the addon price
• Keeping aggregation config here avoids an extra linking step and simplifies setup

UBB Configuration Fields

When editing an addon price with Per Unit Pricing or Volume Pricing, a Usage-Based Billing configuration section appears with the following fields:

The addon price’s existing fields handle the pricing side:

Aggregation Methods

Filter Conditions

Filters narrow the aggregation to specific subsets of the usage event stream. Filters are specified as a JSON object where keys are event property names and values are the required values.

Examples

Bill only production API calls:

{"environment": "production"}

Bill premium-tier storage:

{"tier": "premium"}

Bill specific endpoint usage:

{"endpoint": "/v1/translate", "method": "POST"}

Multiple key-value pairs are combined with AND logic — all conditions must match.

Configuration Walkthrough

Step 1: Create or Edit an Addon Price

1. Navigate to Catalogue > Addons
2. Select or create an addon
3. Add or edit an addon price with Per Unit Pricing or Volume Pricing model

Step 2: Configure UBB Fields

When the pricing model is Per Unit or Volume, the Usage-Based Billing section appears in the addon price form:

1. Event Type — Enter the event type that your application sends (e.g., api_call). This must match the event_type field in your usage events.
2. Aggregation Method — Select how events should be combined (COUNT, SUM, MIN, MAX, AVG)
3. Aggregation Property — For SUM/MIN/MAX/AVG, specify which event property to aggregate (e.g., total_tokens, gb_used). This field is hidden for COUNT.
4. Filters — Optionally enter a JSON object to filter events (e.g., {"region": "us-east"})

Step 3: Set Pricing

Use the standard addon price fields:

• Quantity = Included quantity (units bundled at no extra charge). Set to 0 for pure pay-as-you-go.
• Price = Overage unit price (per-unit charge beyond included quantity)

Example Configurations

API Calls (COUNT-based)

Result: First 10,000 production API calls free, then $0.005 per call.

Token Processing (SUM-based)

Result: Pure PAYG — every token is billed at $0.00003.

Peak Storage (MAX-based)

Result: First 50 GB included, overage billed at peak usage × $0.10/GB.

Multiple UBB Addons Per Subscription

A subscription can have multiple addon prices with UBB configuration, each tracking a different usage dimension independently. For example:

Each produces a separate usage aggregation record and invoice line item.

Billing Formula

At billing cycle end, BillHive computes for each UBB-configured addon price:

raw_quantity    = AGGREGATE(matching events in billing period)
billable_qty    = max(0, raw_quantity - included_quantity)
charge_amount   = billable_qty × overage_unit_price

Automatic Billing at Renewal

When a subscription renews, BillHive automatically computes usage aggregations and includes them in the renewal order as Addon order items with usage metadata. This section describes how addon price UBB configuration flows through to the order and invoice.

How Aggregations Become Order Items

During the renewal flow, the compute-usage-aggregations step evaluates each UBB-configured addon price on the subscription. For each addon price with billable usage (overage quantity > 0), an aggregation record is created and then added to the renewal order as an Addon order item with isMeteredUsage: true in its options.

Each order item is constructed from the aggregation as follows:

Aggregation Status Lifecycle

Each usage aggregation record has a status field that tracks its progress through billing:

When the renewal order is created, the system updates each included aggregation record:

• Sets status from COMPUTED to BILLED
• Sets order_id to the newly created renewal order ID

This status tracking ensures aggregations are never double-billed and provides a clear audit trail linking each usage charge back to its order.

Example Flow

1. Subscription has an addon price for API calls: COUNT aggregation on api_call events, 10,000 included, $0.005 overage
2. During the billing period, 15,000 api_call events are ingested
3. At renewal, aggregation computes: raw = 15,000, included = 10,000, billable = 5,000, amount = $25.00
4. Aggregation record is created with status = COMPUTED
5. Renewal order is created with an Addon item (isMeteredUsage: true): itemId = addon price ID, quantity = 5,000, amount = $25.00
6. Aggregation record is updated: status = BILLED, order_id = renewal order ID
7. Invoice is generated from the order, including the $25.00 usage line item

Best Practices

1. Match event types exactly — The event type on the addon price must match the event_type field in your usage events exactly (case-sensitive)
2. Use COUNT for simple metering — When you just need to count occurrences, COUNT is simplest and doesn’t require an aggregation property
3. Use SUM with quantity fallback — If no aggregation property is specified for SUM, BillHive falls back to summing the event’s quantity field
4. Keep filters simple — Use flat key-value JSON filters. Complex nested conditions are not supported.
5. Test with Compute Now — Use the “Compute Now” button on the subscription’s Usage tab to preview aggregation results before the billing cycle runs