Aggregators

Aggregators turn raw usage events into a single metric, such as API calls, active users, or storage consumed. You can use that metric for subscription billing or, with the Customer Intelligence module, assign it directly to customers for monitoring without billing them. Aggregators are managed independently in Usage > Aggregators and can be linked to multiple products.

​

Subscription billing or direct customer assignment

An aggregator can reach a customer in two ways: The same aggregator can be used in both configurations. If it is both part of a subscription and assigned directly to the same customer, Hyperline avoids showing a duplicate usage card. The subscription’s metering period takes precedence for the subscription-linked card.

​

Operations

An aggregator uses one of three operations to compute a usage metric from your events:

​

Count

Counts the number of matching events. Use this when you bill based on the number of occurrences (e.g., API calls, logins, transactions).

​

Sum

Sums the value of a specific numeric property across matching events. Use this when you bill based on a cumulative measure (e.g., data transferred in GB, compute hours consumed). When using Sum, you must specify which event property to aggregate.

​

SQL formulas

Use SQL formula when Count or Sum is not enough, and you need to combine, compare, or adjust values before billing them. A formula runs on the events selected by the aggregator’s Event type and Filters. Write event properties directly by name, and place them inside an aggregate function: You can then combine those results: Use Test formula before saving to preview the result on matching events.

​

Configuration

When creating an aggregator, you configure the following:

• Name: A descriptive label for the aggregator
• Event type: The type of event to aggregate (e.g., api_calls, storage, users)
• Operation: Count, Sum, or SQL formula (and the target property for Sum)
• Unit name: The label displayed alongside aggregated values (e.g. API calls, GB, seats). Surfaces on usage charts, prices, invoices, and the customer portal.
• Filters: Optional conditions to narrow which events are included. Filters support AND/OR logic with operators like equals, in, gte, lt, etc.
• Exposed event keys: Event fields to surface in the UI for transparency and debugging
• Allow negative values: Whether the aggregated result can go below zero

​

Default aggregation interval

You can set a default aggregation interval on an aggregator by specifying a count and a period (days, weeks, months, or years). It is used to display and evaluate the metric when the aggregator is assigned directly to customers without a subscription. For an aggregator used through a subscription, the subscription’s metering period determines the current value instead. The aggregator’s default interval does not change how that subscription is billed.

​

Aggregator filters

Aggregator filters let you define named filter sets on an aggregator. Each filter combines conditions using AND/OR logic on event properties (e.g., region equals "eu", plan in ["pro", "enterprise"]). Filters serve two purposes:

• Billing: different prices can apply based on which filter an event matches (see price metering filters)
• Usage visualization: on the customer Usage tab, each filter is displayed as a separate line on the usage chart with its own color and legend entry

A filter can only be deleted if it is not referenced by any product price.

​

Thresholds

Thresholds let you define alert conditions on an aggregator. Each threshold specifies:

• Name (optional): A descriptive label for the threshold
• Operator: Greater than or equal to (>=) or less than or equal to (<=)
• Value: The numeric threshold value

Thresholds are evaluated separately for each customer to whom the aggregator applies:

• For a subscription-linked aggregator, Hyperline uses the subscription’s metering period.
• For an aggregator assigned directly to customers, Hyperline uses its default aggregation interval. This direct monitoring workflow requires the Customer Intelligence module.

When a customer’s aggregated usage crosses a threshold, Hyperline can notify you via webhooks (aggregator.threshold_crossed event) or Slack notifications. A threshold alert does not create a charge or change an invoice. On the customer Usage tab, thresholds are displayed as dashed horizontal reference lines on the usage chart, with the operator and value shown as labels.

​

Which products use aggregators?

Not all product types require an aggregator. Here’s when you need one:

​

Managing aggregators

Navigate to Usage > Aggregators to create, edit, and delete aggregators.

​

Create an aggregator

Click New aggregator, configure the operation, event type, and optional filters, then save.

​

Edit an aggregator

Click on an existing aggregator to update its configuration. The detail page also shows which products are currently linked to this aggregator.

​

Delete an aggregator

An aggregator can only be deleted if no products are linked to it.

​

Linking an aggregator to a product

When creating or editing a usage-based, credit, or connected seat product, you select an existing aggregator from a dropdown instead of configuring metering inline.

• Usage products: select any aggregator (count or sum)
• Credit products: select any aggregator (count or sum)
• Seat products: select a count aggregator (only when connected seats are enabled)

For more details on product configuration, see Products and prices.

​

Price metering filters

For usage-based products, you can further refine billing by adding metering filters at the price level. This allows different prices for the same product based on specific event properties (e.g., region, instance type). Learn more in the usage-based product documentation.