Skip to main content

Usage Events and Aggregation

Billing (PBM) supports usage-based (metered) billing through a pipeline of raw event ingestion, aggregation, and billing. This page explains how raw usage events flow through the system and are transformed into billable quantities.

Usage events​

Raw usage events represent individual occurrences of metered activity — for example, an API call, a message sent, or a resource consumed.

Each event captures:

  • Event code — a short identifier for the event type (e.g. api_call, storage_gb)
  • Event date — when the event occurred
  • Event payload — a flexible JSON object containing the value to be aggregated and customer identification
  • Aggregation record link — set after the event has been processed by the aggregation engine

Usage ingestion​

Usage events can be submitted by approved external systems and APIs. This makes it straightforward for backend services to record metered usage as it occurs.

The event payload is deliberately flexible. The aggregation rules (covered in the Usage Aggregation Rules page) determine which fields within the payload are extracted for billing calculations.

Aggregation records​

Aggregation records store the computed result of applying an aggregation rule to a set of usage events for a specific subscription line and billing period.

Each record captures:

  • Which rule was used to aggregate
  • Which subscription line the usage applies to
  • What period was covered (start and end dates)
  • How many events were processed
  • The accumulated quantity — the aggregated result, stored with high precision for accurate billing

How aggregation works​

The aggregation process runs in the billing engine and follows these steps:

The complete pipeline​

Putting it all together, the usage billing pipeline looks like this:

  1. External systems submit raw usage events as they occur
  2. The aggregation engine periodically processes unprocessed events
  3. It reads the relevant aggregation rules to know what to match and how to calculate
  4. It writes the result to an aggregation record with the accumulated quantity
  5. Invoice generation uses the accumulated quantity multiplied by the price to determine the charge

Relationship chain​

Each aggregation record ties together the rule that was used, the subscription line the usage applies to, the period covered, and the quantity calculated. This creates a clear audit trail from raw event to final invoice.

Access control​

  • Usage events — customers can only view usage data for organisations they are authorised to access.
  • Aggregation records — customers can only view aggregation results for subscriptions they are authorised to access.