Aviate Metering

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.

Before You Begin

Authentication

The Aviate Plugin uses a JWT based authentication mechanism. Thus, all the APIs listed in this document require a valid token. This can be obtained via the Auth API.

Resources

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:

The following table explains the different aggregation types:

UsageEvent

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

Metering APIs

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

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

Response

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

Retrieve All Billing Meters

Returns all the billing meters corresponding to a tenant/account.

HTTP Request

GET /plugins/aviate-plugin/v1/metering//billingMeters/all

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//billingMeters/all'

Example Response:

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

Request Body

None

Query Parameters

Response

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

Delete Billing Meter

Deletes the latest version of the billing meter.

Note: Since this is an irreversible operation, the query parameter force=true must be specified to proceed with the deletion.

HTTP Request

DELETE /plugins/aviate-plugin/v1/catalog/{meterCode}/billingMeter

Example Request:

curl -X DELETE \
-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/catalog/code1/billingMeter?force=true'

Example Response:

Query Parameters

Response

If successful, returns a status code of 200 and an empty body.

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

Response

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