Usage Aggregation Rules

Usage event aggregation rules define how raw usage events are transformed into billable quantities. Each rule specifies which events to match, which field to extract, and which formula to apply.

Rules are referenced from PCM prices, connecting the pricing model to the usage measurement model. When a subscription line references a price that has an aggregation rule, the billing engine uses usage-based billing rather than fixed-price billing.

Rule structure

Each aggregation rule defines:

Field	Purpose
Rule name	Human-readable identifier
Version	Version identifier for the rule
Event code	Which usage event type to match (e.g. api_call, storage_gb)
Customer source	JSON path within the event payload to extract the customer ID (defaults to customer_id)
Value source type	Where to find the value: from the event payload or from GPM items
Value source	JSON path to the numeric value to aggregate (defaults to value)
Formula	The aggregation calculation to apply

Immutable versioning

Aggregation rules are immutable once created — they cannot be updated, only replaced with a new version. To change a rule, create a new version with the same rule name.

The system automatically manages which version is current:

1. When a new version is created, it becomes the current version
2. All previous versions of the same rule name are marked as no longer current
3. Exactly one version of each named rule is current at any time

Why immutability matters

Immutability ensures that historical aggregation records remain valid. If a rule were modified in place, past aggregation records would reference a rule definition that no longer matches what was actually applied. Versioning preserves the full audit trail — you can always look back and see exactly which rule definition produced a given aggregation result.

Aggregation formulas

Formula	Behaviour
SUM	Sum all extracted values (default)
COUNT	Count the number of matching events
COUNT_UNIQUE	Count distinct extracted values
FIRST	Take the first value (by event date)
LAST	Take the last value (by event date)
MAX	Take the maximum value
MIN	Take the minimum value

Value source types

Event payload (default)

The aggregation engine extracts the value from the usage event's payload using the configured JSON path. For example, if the value source is set to metadata.credit_event_value, the engine reads that nested field from the event payload.

GPM items

The aggregation engine looks up the value from GPM (General Product Model) item information instead of the event payload. This is used when the billable quantity comes from product data rather than the event itself.

Rule lines

A single aggregation rule can define multiple matching and extraction patterns through rule lines. Each line within a rule has its own event code, customer source, value source, and formula.

When rule lines are useful

The header-level rule fields define the default matching and aggregation behaviour. Rule lines extend this when a single subscription needs to aggregate from multiple event types or extract values differently for different events.

For example, a "total platform usage" rule might have:

• Line 1: match api_call events, formula = COUNT
• Line 2: match storage_gb events, formula = SUM

Connecting rules to prices

Aggregation rules are referenced from PCM prices. When a subscription line references a price that has an aggregation rule attached, the billing engine knows to:

1. Look up the aggregation rule
2. Find and aggregate matching usage events
3. Use the accumulated quantity (rather than a fixed quantity) when calculating the charge

Access control

• Rules — users can view rules for organisations they are authorised to access and can create new versions when they have the required billing permissions.
• Rule lines — follow the same access model as their parent rules.