Merge pull request #324 from reshmabidikar/aviate-metering-266

Aviate metering documentation
killbill · Jan 6, 2025 · c8b84e8 · c8b84e8
2 parents cbb1e81 + 33bfe30
commit c8b84e8
Show file tree

Hide file tree

Showing 26 changed files with 320 additions and 2 deletions.
diff --git a/source/account.html.md b/source/account.html.md
@@ -27,6 +27,7 @@ menu_items:
   - security
   - aviate-catalog-apis
   - aviate-health-apis
+  - aviate-metering-apis
 
 title: Kill Bill
 

diff --git a/source/admin.html.md b/source/admin.html.md
@@ -27,6 +27,7 @@ menu_items:
   - security
   - aviate-catalog-apis
   - aviate-health-apis
+  - aviate-metering-apis
 
 title: Kill Bill
 

diff --git a/source/aviate-catalog-apis.html.md b/source/aviate-catalog-apis.html.md
@@ -27,6 +27,7 @@ menu_items:
   - security
   - aviate-catalog-apis
   - aviate-health-apis
+  - aviate-metering-apis
 
 title: Kill Bill
 

diff --git a/source/aviate-health-apis.html.md b/source/aviate-health-apis.html.md
@@ -27,6 +27,7 @@ menu_items:
   - security
   - aviate-catalog-apis
   - aviate-health-apis
+  - aviate-metering-apis
 
 title: Kill Bill
 

diff --git a/source/aviate-metering.html.md b/source/aviate-metering.html.md
@@ -0,0 +1,49 @@
+---
+includes: 
+  - aviate-metering-apis
+
+current_page: aviate-metering-apis
+
+menu_items:
+  - index
+  - tenant
+  - catalog
+  - account
+  - payment-method
+  - subscription
+  - bundle
+  - invoice
+  - invoice-item
+  - credit
+  - payment
+  - payment-transaction
+  - invoice-payment
+  - usage
+  - custom-field
+  - tag
+  - tag-definition
+  - export
+  - admin
+  - security
+  - aviate-catalog-apis
+  - aviate-health-apis
+  - aviate-metering-apis
+
+title: Kill Bill
+
+language_tabs:
+   - shell
+   - java
+   - ruby
+   - python
+   - javascript
+   - php
+
+toc_footers:
+  - <a href="mailto:[email protected]">Report a doc problem </a>
+
+search: true
+
+code_clipboard: true
+
+---
diff --git a/source/bundle.html.md b/source/bundle.html.md
@@ -27,6 +27,7 @@ menu_items:
   - security
   - aviate-catalog-apis
   - aviate-health-apis
+  - aviate-metering-apis
 
 
 title: Kill Bill

diff --git a/source/catalog.html.md b/source/catalog.html.md
@@ -27,6 +27,7 @@ menu_items:
   - security
   - aviate-catalog-apis
   - aviate-health-apis
+  - aviate-metering-apis
 
 title: Kill Bill
 

diff --git a/source/credit.html.md b/source/credit.html.md
@@ -27,6 +27,7 @@ menu_items:
   - security
   - aviate-catalog-apis
   - aviate-health-apis
+  - aviate-metering-apis
 
 title: Kill Bill
 

diff --git a/source/custom-field.html.md b/source/custom-field.html.md
@@ -27,6 +27,7 @@ menu_items:
   - security
   - aviate-catalog-apis
   - aviate-health-apis
+  - aviate-metering-apis
 
 title: Kill Bill
 

diff --git a/source/export.html.md b/source/export.html.md
@@ -27,6 +27,7 @@ menu_items:
   - security
   - aviate-catalog-apis
   - aviate-health-apis
+  - aviate-metering-apis
 
 title: Kill Bill
 

diff --git a/source/includes/_aviate-catalog-apis.md b/source/includes/_aviate-catalog-apis.md
@@ -1,6 +1,6 @@
 # Aviate Catalog APIs
 
-The Aviate catalog plugin exposes catalog APIs to create individual catalog entries such as plans, products, and pricelists without the need to manage entire catalog versions. This section documents the catalog APIs exported by the Aviate catalog plugin.
+The [Aviate catalog plugin](https://docs.killbill.io/latest/aviate-catalog-plugin) exposes catalog APIs to create individual catalog entries such as plans, products, and pricelists without the need to manage entire catalog versions. This section documents the catalog APIs exported by the Aviate catalog plugin.
 
 ## Before You Begin
 

diff --git a/source/includes/_aviate-health-apis.md b/source/includes/_aviate-health-apis.md
@@ -1,6 +1,6 @@
 # Aviate Health APIs
 
-The Aviate Health feature provides several endpoints that allow you to view the health of your KillBill system and fix problems if any. This section documents the APIs exposed by the Aviate Health feature.
+The [Aviate Health feature](https://docs.killbill.io/latest/aviate-health) provides several endpoints that allow you to view the health of your KillBill system and fix problems if any. This section documents the APIs exposed by the Aviate Health feature.
 
 ## Models
 

diff --git a/source/includes/_aviate_metering-apis.md b/source/includes/_aviate_metering-apis.md
@@ -0,0 +1,247 @@
+# 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:
+
+```shell
+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
+```
+
+```java
+```
+
+```ruby
+```
+
+```python
+```
+
+````php
+````
+
+````javacript
+````
+
+> Example Response:
+
+````json
+[
+  {
+    "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:
+
+```shell
+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'
+```
+
+```java
+```
+
+```ruby
+```
+
+```python
+```
+
+````php
+````
+
+````javacript
+````
+
+> Example Response:
+
+````json
+{
+  "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:
+
+```shell
+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
+```
+
+```java
+```
+
+```ruby
+```
+
+```python
+```
+
+````php
+````
+
+````javacript
+````
+
+**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
+
+
+
+
+
diff --git a/source/index.html.md b/source/index.html.md
@@ -27,6 +27,7 @@ menu_items:
   - security
   - aviate-catalog-apis
   - aviate-health-apis
+  - aviate-metering-apis
 
 title: Kill Bill