From 2eec141cc376d339da2b6f3dee3b017414f5d4f0 Mon Sep 17 00:00:00 2001 From: reshmabidikar Date: Tue, 24 Dec 2024 15:39:08 +0530 Subject: [PATCH] Catalog Usage documentation --- source/includes/_aviate-catalog-apis.md | 160 +++++++++++++++++++++++- 1 file changed, 159 insertions(+), 1 deletion(-) diff --git a/source/includes/_aviate-catalog-apis.md b/source/includes/_aviate-catalog-apis.md index 8c9cc58..138cca7 100644 --- a/source/includes/_aviate-catalog-apis.md +++ b/source/includes/_aviate-catalog-apis.md @@ -16,7 +16,7 @@ Product, plan, and pricelist resources are uniquely identified by the tuple {ten ### Catalog Retrieval/KB Catalog APIs -At the time of writing, the aviate catalog plugin does not expose any endpoints for catalog retrieval. Instead, the catalog can be retrieved via the [KB Catalog APIs](https://killbill.github.io/slate/catalog.html#catalog-2). +At the time of writing, the aviate catalog plugin does not expose any endpoints for catalog retrieval. Instead, the catalog can be retrieved via the [KB Catalog APIs](https://apidocs.killbill.io/catalog). ## Models @@ -50,6 +50,7 @@ Represents a plan phase. It has the following attributes: | **durationLength** | int | user | Length of the duration | | **fixedPrices** | List of PriceData | user | List of fixed prices | | **recurringPrices** | RecurringPriceData | user | Recurring price details | +| **usages** | List of UsageData | user | List of usages | ### RecurringPriceData @@ -69,6 +70,43 @@ Represents a price. It has the following attributes: | **currency** | string | user | Price currency | | **value** | string | user | Price value | +### UsageData + +Represents a usage. It has the following attributes: + +| Name | Type | Generated by | Description | +|---------------------|------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **usageName** | string | user | Usage name | +| **usageType** | string | user | Usage type (One of `CONSUMABLE/CAPACITY`. Only `CONSUMABLE` supported at the time of writing) | +| **prettyName** | string | user | Pretty name for the usage | +| **billingPeriod** | string | user | Recurring billing period. One of the value listed [here](https://github.com/killbill/killbill-api/blob/master/src/main/java/org/killbill/billing/catalog/api/BillingPeriod.java) | +| **tierBlockPolicy** | string | user | The tier block policy (One of `ALL_TIER/TOP_TIER`). Applicable only for `CONSUMABLE` usage type. | +| **tiers** | List of TierData | user | Usage price tiers | + +### TierData + +Represents a usage tier. It has the following attributes: + +| Name | Type | Generated by | Description | +|----------------|-------------------|--------------|-------------| +| **tierNumber** | int | user | Tier number | +| **blocks** | List of BlockData | user | Tier blocks | + +### BlockData + +Represents a tier block. It has the following fields: + +| Name | Type | Generated by | Description | +|----------------------|-------------------|--------------|---------------------| +| **billingMeterCode** | string | user | Billing meter code | +| **size** | int | user | Block size | +| **max** | int | user | Max value in block | +| **prices** | List of PriceData | user | Usage price details | + + + ### ProductData Represents a product. It has the following attributes: @@ -252,6 +290,7 @@ Creates a new plan. If the plan identified by `plan#name` already exists, return > Example Request: ```shell +## without usages curl -X POST \ -H'Content-Type: application/json' \ -H"Authorization: Bearer ${ID_TOKEN}" \ @@ -289,6 +328,70 @@ curl -X POST \ ] }' \ 'http://127.0.0.1:8080/plugins/aviate-plugin/v1/catalog/plan' + +## with usages +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": "standard-weekly", + "prettyName": "Standard Weekly", + "recurringBillingMode": "IN_ADVANCE", + "effectiveDate": "2023-01-01T12:00", + "pricelistName": "DEFAULT", + "productName": "Standard", + "phases": [ + { + "prettyName": "Standard Weekly Evergreen", + "type": "EVERGREEN", + "durationUnit": "UNLIMITED", + "durationLength": -1, + "fixedPrices": [ + { + "currency": "USD", + "value": "1" + } + ], + "recurringPrices": { + "billingPeriod": "WEEKLY", + "prices": [ + { + "currency": "USD", + "value": "3" + } + ] + }, + "usages": [ + { + "usageName": "u1", + "usageType": "CONSUMABLE", + "billingPeriod": "MONTHLY", + "tiers": [ + { + "tierNumber": 1, + "blocks": [ + { + "billingMeterCode": "meter1", + "size": 1, + "max": 1000, + "prices": [ + { + "currency": "USD", + "value": "20.000000000" + } + ] + } + ] + } + ] + } + ] + } + ] +}' \ +'http://127.0.0.1:8080/plugins/aviate-plugin/v1/catalog/plan' ``` ```java @@ -352,6 +455,8 @@ In addition, the following rules are applicable: * A `NON-TRIAL` phase must have at least one fixed or recurring price * An `EVERGREEN` phase must have at least one recurring price +Optionally, each PhaseData can include one or more `usages` corresponding to usage data. + **Query Parameters** | Name | Type | Required | Default | Description | @@ -508,6 +613,12 @@ curl -X DELETE \ ````javacript ```` +> Example Response: + + + +**Request Body** + **Query Parameters** | Name | Type | Required | Default | Description | @@ -518,3 +629,50 @@ curl -X DELETE \ **Response** If successful, returns a status code of 200 and an empty body. + +### Create Billing Meters + +Creates a billing meter. If the meter identified by `billingMeter#name`, `billingMeter#eventKey` and `billingMeter#eventFilters` already exists, returns an error. + +Create Billing Meters. + +**HTTP Request** + +`POST /plugins/aviate-plugin/v1/catalog/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' \ +'http://127.0.0.1:8080/plugins/aviate-plugin/v1/catalog/billingMeters' +``` + +```java +``` + +```ruby +``` + +```python +``` + +````php +```` + +````javacript +```` + +**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 \ No newline at end of file