diff --git a/source/account.html.md b/source/account.html.md index e4b91f4..15bd0a9 100644 --- a/source/account.html.md +++ b/source/account.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/admin.html.md b/source/admin.html.md index f358890..4ea6f84 100644 --- a/source/admin.html.md +++ b/source/admin.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/aviate-catalog-apis.html.md b/source/aviate-catalog-apis.html.md new file mode 100644 index 0000000..1fc5412 --- /dev/null +++ b/source/aviate-catalog-apis.html.md @@ -0,0 +1,47 @@ +--- +includes: + - aviate-catalog-apis + +current_page: aviate-catalog-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 + +title: Kill Bill + +language_tabs: + - shell + - java + - ruby + - python + - javascript + - php + +toc_footers: + - Report a doc problem + +search: true + +code_clipboard: true + +--- \ No newline at end of file diff --git a/source/bundle.html.md b/source/bundle.html.md index 6ce653f..8e82e47 100644 --- a/source/bundle.html.md +++ b/source/bundle.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/catalog.html.md b/source/catalog.html.md index 69b8ac4..9670898 100644 --- a/source/catalog.html.md +++ b/source/catalog.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/credit.html.md b/source/credit.html.md index 72aff21..3a07fa1 100644 --- a/source/credit.html.md +++ b/source/credit.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/custom-field.html.md b/source/custom-field.html.md index f0ece07..a6fd9c5 100644 --- a/source/custom-field.html.md +++ b/source/custom-field.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/export.html.md b/source/export.html.md index ded7b28..87d0aff 100644 --- a/source/export.html.md +++ b/source/export.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/includes/_aviate-catalog-apis.md b/source/includes/_aviate-catalog-apis.md new file mode 100644 index 0000000..8c9cc58 --- /dev/null +++ b/source/includes/_aviate-catalog-apis.md @@ -0,0 +1,520 @@ +# 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. + +## Before You Begin + +### Tenancy & Account-level + +Each of the aviate plugin endpoints below require specifying the standard Kill Bill `X-killbill-apiKey` and `X-killbill-apisecret` headers, which identify the tenant that should be used. In addition, it is possible to specify an optional `accountId` query parameter to create/access catalog entries on a per-account level. + +The Kill Bill system will retrieve such entries from the plugin each time there is a need to access the catalog for a particular tenant. If there are per-account entries, only these entries will be returned for the matching account. + +### Idempotency + +Product, plan, and pricelist resources are uniquely identified by the tuple {tenantId, name}. If such a resource was created with or without an accountId, retrying the create call will be idempotent. If the call is however retried with a different accountId (or lackthereof) it will fail with a validation error. + +### 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). + +## Models + +This section lists the models used by the Catalog APIs + +### PlanData + +Represents a plan. It has the following attributes: + +| Name | Type | Generated by | Description | +|-------------------------------------------|-------------------|--------------|------------------------------------------------------------------------------------------------------------------| +| **name** | string | user | Plan name | +| **prettyName** | string | user | Pretty name for the plan | +| **recurringBillingMode** | string | user | Billing mode (One of `IN_ADVANCE/IN_ARREAR`). Currently, only `IN_ADVANCE` is supported | +| **effectiveDate** | DateTime | user | DateTime when this plan is effective | +| **effectiveDateForExistingSubscriptions** | DateTime | user | DateTime when the price change is effective for existing subscriptions. (Applicable only for plan modifications) | +| **productName** | string | user | Name of the product to which the plan belongs | +| **pricelistName** | string | user | Name of the pricelist to which the plan belongs | +| **retired** | boolean | user | Flag that indicates if a plan is retired +| **phases** | List of PhaseData | user | list of phases in the plan | + +### PhaseData + +Represents a plan phase. It has the following attributes: + +| Name | Type | Generated by | Description | +|---------------------|--------------------|--------------|------------------------------------------------------------------------| +| **prettyName** | string | user | Pretty name for the phase | +| **type** | string | user | Phase type (One of `TRIAL/EVERGREEN/FIXEDTERM/DISCOUNT`) | +| **durationUnit** | string | user | Duration unit for a phase (One of `DAYS/WEEKS/MONTHS/YEARS/UNLIMITED`) | +| **durationLength** | int | user | Length of the duration | +| **fixedPrices** | List of PriceData | user | List of fixed prices | +| **recurringPrices** | RecurringPriceData | user | Recurring price details | + +### RecurringPriceData + +Represents recurring price information. It has the following attributes: + +| Name | Type | Generated by | Description | +|-------------------|-------------------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **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) | +| **prices** | List of PriceData | user | List of recurring prices | + +### PriceData + +Represents a price. It has the following attributes: + +| Name | Type | Generated by | Description | +|--------------|-----------|--------------|----------------| +| **currency** | string | user | Price currency | +| **value** | string | user | Price value | + +### ProductData + +Represents a product. It has the following attributes: + +| Name | Type | Generated by | Description | +|----------------|--------------|--------------|-------------------------------------------------------------------------------------------------------| +| **name** | string | user | Product name | +| **prettyName** | string | user | Pretty name for the product | +| **category** | string | user | Product category (`BASE/ADD_ON/STANDALONE`) | +| **availableForBps** | string array | user | An array of base product names for which this addon is available (Applicable only for addon products) | +| **availableAddons** | string array | user | An array of addon product names available on this base product (Applicable only for base products) | + +### CatalogInputData + +Represents the plans, products and pricelists to be created. It has the following attributes: + +| Name | Type | Generated by | Description | +|----------------|---------------------|--------------|-----------------------------------------| +| **catalogName** | string | user | Catalog name | +| **plans** | List of PlanData | user | List of plans included in this input | +| **products** | List of ProductData | user | List of products included in this input | + + +## Endpoints + +### Create Plan, Product, Pricelist + +Creates one or multiple plans, products, and pricelists. This is a combo API that can be used to create a plan, its product, and pricelist in one go. If the plan identified by `plan#name` already exists, returns the existing plan. If the plan pricelist (identified by `plan#pricelistName`) is missing, creates it. If the plan product (identified by `plan#productName`) is missing and not specified as part of `products`, returns an error. + +**HTTP Request** + +`POST /plugins/aviate-plugin/v1/catalog/inputData` + +> 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 '{ + "plans": [ + { + "name": "premium-annual", + "prettyName": "Premium Annual", + "recurringBillingMode": "IN_ADVANCE", + "pricelistName": "DEFAULT", + "productName": "Premium", + "phases": [ + { + "prettyName": "Premium Annual Evergreen", + "type": "EVERGREEN", + "durationUnit": "UNLIMITED", + "durationLength": -1, + "fixedPrices": [ + { + "currency": "USD", + "value": "0.50" + } + ], + "recurringPrices": { + "billingPeriod": "ANNUAL", + "prices": [ + { + "currency": "USD", + "value": "15" + } + ] + } + } + ] + } + ], + "products": [ + { + "name": "Premium", + "category": "BASE" + } + ] +}' \ +http://127.0.0.1:8080/plugins/aviate-plugin/v1/catalog/inputData +``` + +```java +``` + +```ruby +``` + +```python +``` + +````php +```` + +````javacript +```` + +> Example Response: + +```json +{ + "plans": [ + { + "name": "premium-annual", + "prettyName": "Premium Annual", + "recurringBillingMode": "IN_ADVANCE", + "pricelistName": "DEFAULT", + "productName": "Premium", + "phases": [ + { + "prettyName": "Premium Annual Evergreen", + "type": "EVERGREEN", + "durationUnit": "UNLIMITED", + "durationLength": -1, + "fixedPrices": [ + { + "currency": "USD", + "value": "0.50" + } + ], + "recurringPrices": { + "billingPeriod": "ANNUAL", + "prices": [ + { + "currency": "USD", + "value": "15" + } + ] + } + } + ] + } + ], + "products": [ + { + "name": "Premium", + "category": "BASE" + } + ] +} +``` + +**Request Body** + +A `CatalogInputData` list. At the minimum, one `PlanData` object need to be included. + +For each `PlanData`, the following fields must be specified: `name`, `recurringBillingMode`, `pricelistName`, `productName`, `effectiveDate`, one or more `phases`. For each phase, the following fields must be specified: `phaseType`, `durationUnit`, `durationLength`. In addition, the following rules are applicable: + +* A `TRIAL` phase cannot have recurring prices +* A `NON-TRIAL` phase must have at least one fixed or recurring price +* An `EVERGREEN` phase must have at least one recurring price + +If a `ProductData` object is specified, at the minimum, the following fields need to be specified: `name`, `category`. In addition, the following rules are applicable: + +* If `product#category` is `ADD_ON`, at least one value needs to be specified for `product#availableForBps`. +* If `product#category` is `ADD_ON`, no values should be specified for `product#availableAddons` +* If `product#category` is `BASE`, no values should be specified for `product#availableForBps`. + +**Query Parameters** + +| Name | Type | Required | Default | Description | +|-------------------------------------------|--------|----------| ---- |----------------------------------------------------------- +| **accountId** | UUID | false | none | Account Id for which to create the plan/product/pricelist | + + +**Response** + +If successful, returns a status code of 201 and the `CatalogInputData` object. + + +### Create Plan + +Creates a new plan. If the plan identified by `plan#name` already exists, returns the existing plan. If the underlying pricelist (identified by `plan#pricelistName`) is missing, creates it. If the underlying product (identified by `plan#productName`) is missing, returns an error. In other words, the caller of this API needs to ensure that the product corresponding to the plan exists in KB before invoking this endpoint. At the time of writing, the product can be created only via the [Create Plan/Product/Pricelist](aviate-catalog-apis.html#create-plan-product-pricelist) endpoint. + +**HTTP Request** + +`POST /plugins/aviate-plugin/v1/catalog/plan` + +> 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": "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" + } + ] + } + } + ] +}' \ +'http://127.0.0.1:8080/plugins/aviate-plugin/v1/catalog/plan' +``` + +```java +``` + +```ruby +``` + +```python +``` + +````php +```` + +````javacript +```` + +> Example Response: + +```json +{ + "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" + } + ] + } + } + ] +} +``` + +**Request Body** + +A `PlanData` object. As a minimum, the following fields must be specified: `name`, `recurringBillingMode`, `pricelistName`, `productName`, `effectiveDate`, one or more `PhaseData`. For each `PhaseData`, the following fields must be specified: `phaseType`, `durationUnit`, `durationLength`. + +In addition, the following rules are applicable: + +* A `TRIAL` phase cannot have recurring prices +* A `NON-TRIAL` phase must have at least one fixed or recurring price +* An `EVERGREEN` phase must have at least one recurring price + +**Query Parameters** + +| Name | Type | Required | Default | Description | +|------------------------------|---------|----------| ---- |----------------------------------------- +| **accountId** | UUID | false | none | Account Id for which to create the plan | + + +**Response** + +If successful, returns a status code of 201 and the `PlanData` object. + +### Modify Plan + +This API is intended to modify price points associated with an existing plan. If the plan identified by `planName` does not exist, returns an error. When using the API, one must specify all the prices - whether fixed and/or recurring - for all the original phases configured on the plan even if the prices for some of the phases remain unchanged. Other attributes like duration of the phases, etc. are not allowed to be changed. Note that this behavior differs from the `/1.0/kb/catalog` KB APIs where phases from the same plan can be changed through catalog versions. Instead, of overloading the same plan in a future catalog version, we want to encourage users to create separate plans when those have different phases. + +**HTTP Request** + +`PUT /plugins/aviate-plugin/v1/catalog/{planName}/updatePlan` + +> Example Request: + +```shell +curl -X PUT \ +-H'Content-Type: application/json' \ +-H"Authorization: Bearer ${ID_TOKEN}" \ +-H'X-killbill-apiKey: alphaF' \ +-H'X-killbill-apisecret: alphaF' \ +-d '[ + { + "type": "EVERGREEN", + "fixedPrices": [ + { + "currency": "USD", + "value": "15" + } + ], + "recurringPrices": { + "prices": [ + { + "currency": "USD", + "value": "30" + } + ] + } + } + ]' \ +'http://127.0.0.1:8080/plugins/aviate-plugin/v1/catalog/premium-monthly/updatePlan' +``` + +```java +``` + +```ruby +``` + +```python +``` + +````php +```` + +````javacript +```` + +> Example Response: + +```json +{ + "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": "15" + } + ], + "recurringPrices": { + "billingPeriod": "WEEKLY", + "prices": [ + { + "currency": "USD", + "value": "30" + } + ] + } + } + ] +} +``` + +**Request Body** + +A `PhaseData` List. As mentioned earlier, one must specify all the prices - whether fixed and/or recurring - for all the original phases configured on the plan even if these prices are unchanged. Other attributes like duration of the phases, etc. are not allowed to be changed. + +**Query Parameters** + +| Name | Type | Required | Default | Description | +|-------------------------------------------|--------|----------|------------------|------------------------------------------------------------- +| **effectiveDateForExistingSubscriptions** | String | false | none | Datetime when the price change is applicable for existing subscriptions | +| **effectiveDate** | UUID | false | Current DateTime | Datetime when the plan change is effective | +| **accountId** | UUID | false | none | Account Id to which the plan belongs | + +**Notes:** + +* If `effectiveDateForExistingSubscriptions` is specified, it is necessary to specify `effectiveDate` +* If both `effectiveDateForExistingSubscriptions` and `effectiveDate` are specified, `effectiveDateForExistingSubscriptions` cannot be prior to `effectiveDate` + + +**Response** + +If successful, returns a status code of 201 and the modified `PlanData` object. + +### Retire Plan + +Retire an existing plan + +**HTTP Request** + +`DELETE /plugins/aviate-plugin/v1/catalog/{planName}/retirePlan` + +> Example Request: + +```shell +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/premium-monthly/retirePlan' +``` + +```java +``` + +```ruby +``` + +```python +``` + +````php +```` + +````javacript +```` + +**Query Parameters** + +| Name | Type | Required | Default | Description | +|-------------------------------------------|--------|----------| ---- |------------------------------------------------------------------------- +| **accountId** | UUID | false | none | Account Id to which the plan belongs | + + +**Response** + +If successful, returns a status code of 200 and an empty body. diff --git a/source/index.html.md b/source/index.html.md index 29bd4d2..0fce6d2 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/invoice-item.html.md b/source/invoice-item.html.md index c5fb73b..f29cbec 100644 --- a/source/invoice-item.html.md +++ b/source/invoice-item.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/invoice-payment.html.md b/source/invoice-payment.html.md index 0a2e45a..c34c53b 100644 --- a/source/invoice-payment.html.md +++ b/source/invoice-payment.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/invoice.html.md b/source/invoice.html.md index 23077c3..2dff9a1 100644 --- a/source/invoice.html.md +++ b/source/invoice.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/payment-method.html.md b/source/payment-method.html.md index 9a66e11..b709d7c 100644 --- a/source/payment-method.html.md +++ b/source/payment-method.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/payment-transaction.html.md b/source/payment-transaction.html.md index a99a040..3e61697 100644 --- a/source/payment-transaction.html.md +++ b/source/payment-transaction.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/payment.html.md b/source/payment.html.md index 58e653c..0c6b4fe 100644 --- a/source/payment.html.md +++ b/source/payment.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/security.html.md b/source/security.html.md index e3aee74..6c10ee3 100644 --- a/source/security.html.md +++ b/source/security.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/subscription.html.md b/source/subscription.html.md index a48ca8d..77698c4 100644 --- a/source/subscription.html.md +++ b/source/subscription.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/tag-definition.html.md b/source/tag-definition.html.md index 9cccd84..f8a4795 100644 --- a/source/tag-definition.html.md +++ b/source/tag-definition.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/tag.html.md b/source/tag.html.md index f8e142b..d87dac5 100644 --- a/source/tag.html.md +++ b/source/tag.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/tenant.html.md b/source/tenant.html.md index 4fb6197..f4cb6c5 100644 --- a/source/tenant.html.md +++ b/source/tenant.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill diff --git a/source/usage.html.md b/source/usage.html.md index 283a032..da44298 100644 --- a/source/usage.html.md +++ b/source/usage.html.md @@ -25,6 +25,7 @@ menu_items: - export - admin - security + - aviate-catalog-apis title: Kill Bill