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.

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
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:

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

Example Response:

{
  "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 endpoint.

HTTP Request

POST /plugins/aviate-plugin/v1/catalog/plan

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": "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'

Example Response:

{
  "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:

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'

Example Response:

{
  "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:

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'

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.