Aviate Metering APIs

The Aviate plugin offers a metering feature that allows performing usage aggregation. As part of this functionality, the plugin exposes some metering APIs. These APIs provide the ability to create billing meters and record usage data against these meters. This section documents the metering APIs exported by the Aviate plugin.

Models

BillingMeter

A BillingMeter encapsulates how usages are aggregated. Before recording a usage, it is necessary to create a billing meter corresponding to it.

It has the following fields:

Name	Type	Generated by	Description
code	string	user	Billing meter code
name	string	user	Billing meter name
eventKey	string	user	The event to aggregate on
eventFilters	List of String	user	Filters to be used to filter the events
aggregationType	string	user	Specifies how the usage events should be aggregated. Possible values are `COUNT`, `UNIQUE_COUNT`, `LATEST`, `MAX`, `SUM`

The following table explains the different aggregation types:

Aggregation Type	Explanation
COUNT	TODO
UNIQUE_COUNT	TODO
LATEST	TODO
MAX	TODO
SUM	TODO

UsageEvent

A UsageEvent represents a single usage to be recorded. It has the following fields:

Name	Type	Generated by	Description
billingMeterCode	string	user	Billing meter code
subscriptionId	string	user	ID of the subscription against which usages should be recorded
trackingId	string	user	User's tracking Id for this usage
timeStamp	string	user	DateTime corresponding to the usage
value	number	user	Amount of usage

Endpoints

Create Billing Meter

Creates billing meters. If the meter identified by billingMeter#name, billingMeter#eventKey and billingMeter#eventFilters already exists, returns an error.

HTTP Request

POST /plugins/aviate-plugin/v1/metering/billingMeters

Example Request:

curl -X POST \
     -H'Content-Type: application/json' \
     -H"Authorization: Bearer ${ID_TOKEN}" \     
     -H'X-killbill-apiKey: alphaF' \
     -H'X-killbill-apisecret: alphaF' \
     -d '[
          {
            "name": "meter1",
            "code": "meter1",
            "eventKey": "eventKey",
            "eventFilters": ["filter1", "filter2"],
            "aggregationType": "SUM"
          }
         ]' \
    http://127.0.0.1:8080/plugins/aviate-plugin/v1/metering/billingMeters

Example Response:

[
  {
    "name": "meter1",
    "code": "meter1",
    "eventKey": "eventKey",
    "eventFilters": [
      "filter1",
      "filter2"
    ],
    "aggregationType": "SUM"
  }
]

Request Body

A BillingMeter list. At the minimum, one BillingMeter object need to be specified. For each BillingMeter, the following fields must be specified: code,name, eventKey, aggregationType.

Query Parameters

Name	Type	Required	Default	Description
accountId	UUID	false	none	Account Id to which the billing meter belongs

Response

If successful, returns a status code of 200 and a BillingMeter list

Retrieve Billing Meter

Returns the BillingMeter corresponding to the specified meter code.

HTTP Request

GET /plugins/aviate-plugin/v1/metering/{metercode}/billingMeter

Example Request:

curl -X GET \
-H'Content-Type: application/json' \
-H"Authorization: Bearer ${ID_TOKEN}" \
-H'X-killbill-apiKey: alphaF' \
-H'X-killbill-apisecret: alphaF' \
'http://127.0.0.1:8080/plugins/aviate-plugin/v1/metering/meter1/billingMeter'

Example Response:

{
  "name": "meter1",
  "code": "meter1",
  "eventKey": "eventKey",
  "eventFilters": [
    "filter1",
    "filter2"
  ],
  "aggregationType": "SUM"
}

Request Body

None

Query Parameters

Name	Type	Required	Default	Description
accountId	UUID	false	none	Account Id to which the billing meter belongs

Response

If successful, returns a status code of 200 and a BillingMeter object.

Submit Usage Events

Submits usage events.

HTTP Request

POST /plugins/aviate-plugin/v1/metering/billing/{accountID}

Example Request:

curl -X POST \
-H'Content-Type: application/json' \
-H"Authorization: Bearer ${ID_TOKEN}" \
-H'X-killbill-apiKey: alphaF' \
-H'X-killbill-apisecret: alphaF' \
     -d '[
  {
    "billingMeterCode": "meter1",
    "subscriptionId": "8e242ddd-eff9-41d9-b8ca-b2ed77b98da3",
    "trackingId": "24f7f19b-7c05-41e5-82aa-2f85c8a332dc",
    "timestamp": "2025-01-01T10:30",
    "value": 1.2
  }
]' \
     http://127.0.0.1:8080/plugins/aviate-plugin/v1/metering/billing/34c72fc8-fbe6-4dd0-b111-0bdaa8c9173d

Request Body

A UsageEvent list.

Query Parameters

Name	Type	Required	Default	Description
pluginProperty ??	List of String	false	none	List of plugin properties, if any. Should be in the format `key%3Dvalue`

Response

If successful, returns a status code of 200 and a UsageEvent list