This is an Aviate-only feature.

Introduction

The Aviate plugin can be used as a catalog plugin. The Aviate catalog plugin serves as an alternative to the XML catalog managed within Kill Bill core. It provides APIs that operate at the plan/product/pricelist level, offering greater flexibility and granularity compared to the catalog version level. These APIs enable users to create individual catalog entries such as plans, products, and pricelists without the need to manage entire catalog versions. The catalog data created through the plugin is stored in tables managed by the Aviate plugin.

When the Aviate catalog plugin features are enabled, the catalog served by the plugin takes priority over any existing catalog entries created from regular KB catalog APIs (/1.0/kb/catalog) documented here.

Getting Started with the Aviate Catalog Plugin

This section provides a step-by-step approach to get started with the Aviate Catalog plugin.

Installing the Plugin

The Aviate plugin can be installed as documented in the How to Install the Aviate Plugin doc.

Enabling Catalog APIs

To use the catalog API capabilities provided by the Aviate plugin, ensure that KB is started with the following property:

com.killbill.billing.plugin.aviate.enableCatalogApis=true

Refer to the Kill Bill Configuration Guide to know more about setting configuration properties.

Using Catalog Plugin APIs

Once the plugin is installed and enabled, you can start using the Catalog Plugin APIs. As mentioned earlier, the Aviate catalog plugin exposes endpoints that operate at a plan/product/pricelist level. These endpoints allow plan/product/pricelist creation/modification and deletion. At the time of writing, only plan-level endpoints are supported. The catalog API endpoints are documented in our api docs.

Catalog Versioning

Since the Kill Bill system internally manages catalog versions, the plugin will construct such multi-version catalog based on the entries that need to be returned.

Each plan stored within the Aviate catalog plugin has an associated effectiveDate. The catalog versions and what they each include is based on the plan#effectiveDate: A new catalog version is created every time a plan is modified (e.g. price change). When this happens, a new version is created with the effectiveDate of the modified plan, and it also includes all the previous plans.

Assuming we have plans p1, p2, p3, p4 that are created and modified at different times (using the prime notation to denote modifications, e.g. p1' is the first modification of p1), and given the following sequence of plan creations/updates: p1, p2, p3, p1', p2', p4, p2'', we get the following catalog versions:

v1: p1, p2, p3           # v1 effectiveDate = p1 effectiveDate
v2: p1', p2, p3          # v2 effectiveDate = p1' effectiveDate
v3: p1', p2', p3, p4     # v3 effectiveDate = p2' effectiveDate
v4: p1', p2'', p3, p4    # v4 effectiveDate = p2'' effectiveDate

Each plan modification triggers a new catalog version so that the effectiveDate of that version matches the effectiveDate of the modified plan. New plan creations (e.g. p4) are included in the most recent open version without creating a new one. If multiple plans are modified with the exact same effectiveDate, they will be grouped in the same catalog version.

FAQs

Is it possible to use the KB catalog APIs when the Aviate catalog plugin is enabled?

When the Aviate catalog plugin is enabled, the catalog state is managed by the Aviate plugin. So, while it is possible to use the GET KB Catalog APIs for catalog retrieval, it is not possible to use the upload/delete KB Catalog APIs endpoints.

Is it possible to use the KB price overrides feature when the Aviate catalog plugin is enabled?

Yes, it is possible to use the KB price overrides feature. In other words, even if the Aviate catalog plugin is enabled, it is still possible to create a subscription with price overrides.