This is an Aviate-only feature.

Introduction

The Aviate plugin offers metering capabilities. The Kill Bill core usage APIs support recording rolled-up usage data, but aggregation must be performed outside Kill Bill. With the introduction of the metering feature, aggregation can now occur directly within Kill Bill by using the metering APIs. Thus, this feature allows users to be charged based on aggregated units seamlessly.

The Aviate Metering feature introduces the concept of a BillingMeter and a UsageEvent. A BillingMeter encapsulates information about how usage points should be aggregated - e.g. sum all points within a specific period. A UsageEvent represents a single usage point. Each UsageEvent has an associated BillingMeter. The UsageEvents are then aggregated based on the aggregation type specified in the associated BillingMeter.

Getting Started with Aviate Metering

This section provides a step-by-step approach to start using the Aviate Metering feature.

Installing the Plugin

The Aviate plugin can be installed as documented in the How to Install the Aviate Plugin doc.

Enabling Aviate Metering

To use the metering capabilities provided by the Aviate plugin, ensure that KB is started with the following property:

com.killbill.billing.plugin.aviate.enableUsageApis=true

Refer to the Kill Bill Configuration Guide to know more about setting configuration properties.

Using Metering APIs

Once the aviate plugin has been installed and the metering feature is enabled, you can start using the Aviate Metering APIs. These APIs enable creation of billing meters and allow to record raw (non aggregated) usage points. These APIs replace the Kill Bill usage APIs: Users should either use existing Kill Bill usage APIs (to record aggregated usage points) or use the Aviate metering APIs discussed in this section. For more details about these APIs, please refer to our api docs.

Note that in the current implementation, the caller should ensure that all usage points for a specific subscription are submitted sequentially (i.e., must not be submitted concurrently).

A Metering Example

This section explains how metering works with an example. We also provide a tutorial with step by step examples.

Assume that we would like to track the cellphone minutes consumed by a user. We can create a BillingMeter as follows:

{
  "name": "cell-phone-minutes",
  "code": "cell-phone-minutes",
  "eventKey": "minutes",
  "aggregationType": "SUM"
}

Note that the SUM aggregationType is used.

UsageEvents can then be recorded corresponding to the cellphone minutes actually consumed by the user.

For example, consider the following UsageEvents:

# event1 - User consumed 10.5 minutes on 2025-01-01T10:30
{
  "billingMeterCode": "cell-phone-minutes",
  "subscriptionId": "8e242ddd-eff9-41d9-b8ca-b2ed77b98da3",
  "trackingId": "t1",
  "timestamp": "2025-01-01T10:30",
  "value": 10.5
}
# event2 - User consumed 15 minutes on 2025-02-01T11:45
{
  "billingMeterCode": "cell-phone-minutes",
  "subscriptionId": "8e242ddd-eff9-41d9-b8ca-b2ed77b98da3",
  "trackingId": "t2",
  "timestamp": "2025-02-01T11:45",
  "value": 15
}

The above JSON snippet specifies two UsageEvents. The value of the value field is aggregated based on the aggregationType in the associated BillingMeter. In the example above, the SUM aggregationType is used, so the values are added and the aggregated usage comes to 10.5+15=25.5.

Note
 Note: At the time of writing, the eventType and eventFilters fields in the BillingMeter are not implemented.