Skip to content

Commit

Permalink
Catalog Usage documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@reshmabidikar
reshmabidikar committed Dec 24, 2024
1 parent a4a6949 commit 2eec141
Showing 1 changed file with 159 additions and 1 deletion.
160 changes: 159 additions & 1 deletion source/includes/_aviate-catalog-apis.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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 |

<!---
Add a link to billingMeterCode resource after it is available
-->

### ProductData

Represents a product. It has the following attributes:
Expand Down Expand Up @@ -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}" \
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -508,6 +613,12 @@ curl -X DELETE \
````javacript
````

> Example Response:


**Request Body**

**Query Parameters**

| Name | Type | Required | Default | Description |
Expand All @@ -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

0 comments on commit 2eec141

Please sign in to comment.