diff --git a/html5/_main_toc.html.slim b/html5/_main_toc.html.slim index a8e61533c..6b17cc830 100644 --- a/html5/_main_toc.html.slim +++ b/html5/_main_toc.html.slim @@ -354,8 +354,11 @@ nav.sidebar-nav a.nav-link href="/latest/aviate-changelog.html" | Aviate Changelog li.bd-sidenav-active - a.nav-link href="/latest/aviate-pricing-hub.html" - | Aviate Pricing Hub Guide + a.nav-link href="/latest/aviate-getting-started.html" + | Getting Started With Aviate + li.bd-sidenav-active + a.nav-link href="/latest/aviate-catalog-guide.html" + | Aviate Catalog Guide li.bd-sidenav-active a.nav-link href="/latest/how-to-install-the-aviate-plugin.html" | Plugin Installation diff --git a/userguide/assets/img/aviate/cloudsprout-plans-products.png b/userguide/assets/img/aviate/cloudsprout-plans-products.png new file mode 100644 index 000000000..82779a0ff Binary files /dev/null and b/userguide/assets/img/aviate/cloudsprout-plans-products.png differ diff --git a/userguide/aviate/aviate-catalog-guide.adoc b/userguide/aviate/aviate-catalog-guide.adoc new file mode 100644 index 000000000..ffbf8035f --- /dev/null +++ b/userguide/aviate/aviate-catalog-guide.adoc @@ -0,0 +1,185 @@ += Aviate Catalog Guide + +== Introduction + +The https://aviate.killbill.io[Aviate Catalog UI] allows you to create individual catalog entries such as products, plans, and pricelists. +This provides much finer granularity than the Kill Bill open-source model, which requires creating a new catalog version for any change. As a result, this approach is more dynamic and scales significantly better when managing a large number of catalog entries. +Internally, the UI uses the https://apidocs.killbill.io/aviate-catalog[Aviate Catalog APIs]. + +== Create Product,Plan, Pricelist + +To create a product, plan, and pricelist: + +. Open the *Create Product, Plan, Pricelist* screen. +. Enter the product name (e.g., `netflix`). +. Define a plan (e.g., `netflix-basic-monthly`). +. Set the price (e.g., `$10` per month). +. Save your entries. + + +Demo: + +++++ +
+ +
+ +
+
+++++ + +API Used: https://apidocs.killbill.io/aviate-catalog#create-plan-product-pricelist[Create Plan, Product, Pricelist API]. + +== Add New Plan + +Once a product exists, you can add additional plans: + +. Select the product (e.g., `netflix`). +. Create a new plan (e.g., `netflix-premium-monthly`). +. Configure phases such as `DISCOUNT` or `EVERGREEN`. +. Save the plan. + + +Demo: + +++++ +
+ +
+ +
+
+++++ + +API used: https://apidocs.killbill.io/aviate-catalog#create-plan[Create Plan API]. + +[[edit_plan]] +== Edit Plan + +The edit plan feature allows you to update plan prices after a plan is created. Note that Other attributes (like *phase duration*) cannot be changed. + +[NOTE] +Editing a plan creates a new version of the plan. Existing subscriptions continue to use the old plan. See https://docs.killbill.io/latest/userguide_subscription#_catalog_versions[docs]. + +. Select the plan (e.g., `netflix-basic-monthly`). +. Adjust the price. +. Save changes. + + +Demo: + +++++ +
+ +
+ +
+
+++++ + +API used: https://apidocs.killbill.io/aviate-catalog#modify-plan[Modify Plan API]. + +== Archive Plan + +You can archive an existing plan. Archiving prevents creating new subscriptions corresponding to the plan. +The plan remains active for existing subscriptions. + +. Select the plan (e.g., `Netflix Usage Monthly`). +. Choose *Archive*. +. Confirm the action. + + +Demo: + +++++ +
+ +
+ +
+
+++++ + +API used: https://apidocs.killbill.io/aviate-catalog#retire-plan[Retire Plan API]. + +== Delete Plan + +You can delete an existing plan permanently. Deleting permanently removes a plan from the database. + +WARNING: Deleting a plan could break the system if there are active subscriptions. Use this only for plans created erroneously that do not have active subscriptions. + +. Select the plan. +. Choose *Delete*. +. Confirm deletion. + + +//Demo: + +API used: https://apidocs.killbill.io/aviate-catalog#delete-plan[Delete Plan API]. + +== Duplicate Plan + +You can create a new plan based on an existing plan. + +[NOTE] +The *Duplicate Plan* feature is a time-saving convenience that lets you quickly create a new plan. When duplicating, all plan attributes can be edited and on saving,a new plan is created. +By contrast, the <> feature is limited to updating prices only, and each change automatically generates a new version of the plan. + +. Select the plan +. Choose *Duplicate* +. Make changes to the plan as desired +. Save the new plan. + +Demo: + +++++ +
+ +
+ +
+
+++++ + + + +== Creating Usage Plans + +Usage plans allow billing based on consumption. See https://docs.killbill.io/latest/userguide_subscription#components-catalog-usage[docs]. + +. Define a https://apidocs.killbill.io/aviate-metering#billingmeter[billing meter] (how usage is tracked). +. Configure *blocks/tiers*. +. Assign usage-based prices to each block. +. Save the plan. + + +Demo: + +++++ +
+ +
+ +
+
+++++ + +API used: https://apidocs.killbill.io/aviate-catalog#create-plan[Create Plan API]. + +//TODO Delete Plan/Product + +//TODO Duplicate Plan/Product + +== Conclusion + +You now know how to: + +* Create products, plans, and pricelists +* Add new plans +* Edit plan prices +* Archive or delete plans +* Duplicate plans +* Build usage-based plans + + + diff --git a/userguide/aviate/aviate-pricing-hub.adoc b/userguide/aviate/aviate-pricing-hub.adoc index ef2ef1b95..09881a423 100644 --- a/userguide/aviate/aviate-pricing-hub.adoc +++ b/userguide/aviate/aviate-pricing-hub.adoc @@ -1,9 +1,9 @@ -= Aviate Pricing Hub += Aviate Catalog Guide == Introduction -The Aviate Pricing Hub allows creating individual catalog entries such as plans, products, and pricelists. Thus, you can create such entries without the need to manage entire catalog versions. -The Pricing Hub UI internally uses the https://apidocs.killbill.io/aviate-catalog[Aviate Catalog APIs]. +The Aviate Catalog UI allows creating individual catalog entries such as plans, products, and pricelists. Thus, you can create such entries without the need to manage entire catalog versions. +The Aviate Catalog UI internally uses the https://apidocs.killbill.io/aviate-catalog[Aviate Catalog APIs]. == Products diff --git a/userguide/aviate/aviate_getting_started.adoc b/userguide/aviate/aviate_getting_started.adoc new file mode 100644 index 000000000..3879cee36 --- /dev/null +++ b/userguide/aviate/aviate_getting_started.adoc @@ -0,0 +1,249 @@ += Getting Started with Aviate and Kaui + +== TL;DR + +In this guide, you will: + +* Use *Aviate* to configure your billing environment. +* Switch to *Kaui* to create your first customer and subscription. +* Generate and view an invoice. +* Understand the role of *Kill Bill*, *Aviate*, and *Kaui*. +* End up with a fully working fictive SaaS company set up for demos. + +The example company used throughout this guide is *CloudSprout*, a fictional SaaS business operating in the UK and France. + +'''' + +== Concepts Overview + +Before starting, it helps to understand how the pieces fit together. + +* *Kill Bill* is the billing engine. It manages accounts, subscriptions, invoices, payments, and taxes. +* *Aviate* is the Enterprise control and management plane. You use it to configure catalogs, taxes, invoice templates, and tenant settings, as well as proactively monitor the health of the billing engine. +* *Kaui* is the billing operations UI. You use it for day-to-day actions such as creating customers, managing subscriptions, and reviewing invoices. + +In short: + +* Use *Aviate* to *set things up*. +* Use *Kaui* to *run billing operations*. + +'''' + +== Step 1: Start in Aviate (Get Started) + +When you first log into Aviate, you land on the *Get Started* screen. + +This checklist guides you through the minimum required setup to bill customers. + +You should complete all steps in order. + +=== Configure company settings + +This step defines who you are as a business. + +For the purpose of this guide, use the following fictive company: + +* Company name: *CloudSprout* +* Business type: B2B SaaS +* Operating countries: + ** United Kingdom (GBP) + ** France (EUR) + +This information is later reused on invoices and customer communications. + +The following demo shows how you can configure the company settings via Aviate. +++++ +
+ +
+ +
+
+++++ + +'''' + +=== Configure the catalog + +The catalog defines what you sell. + +For CloudSprout, create a simple catalog with: + +* A small number of subscription plans (for example Starter, Team, Business). +* Optional add-ons (for example Extra Storage). + +| Plan | GBP | EUR | Notes | +| ----------- | ----------- | ----------- | ----------------- | +| 🌱 Starter | £9 / month | €10 / month | Monthly only | +| 🌿 Team | £29 / month | €32 / month | Monthly or annual | +| 🌳 Business | £79 / month | €89 / month | Annual only | + +| Add-on | GBP | EUR | Billing | +| ---------------- | --- | --- | ------- | +| Extra Storage | £5 | €6 | Monthly | +| Priority Support | £15 | €18 | Monthly | + +The following demo shows how you can create the `CloudSprout Starter` plan via Aviate. +++++ +
+ +
+ +
+
+++++ + +You can similarly create the other plans/products defined above: + +image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/aviate/cloudsprout-plans-products.png[align=center] + +This step only defines products and plans. No customers are created yet. + +'''' + +=== Configure taxes + +Taxes are configured in Aviate and applied automatically by Kill Bill. + +For the demo setup: + +* Create a tax code for the UK (VAT) with a 20% rate. +* Create a tax code for France (VAT) with a 20% rate. +* Set a valid start date. + +Once saved, tax codes can be associated with products. + +The following demo explains how you can configure the above tax codes: + +++++ +
+ +
+ +
+
+++++ + +'''' + +== Step 2: Switch to Kaui (Billing Operations) + +After completing the Aviate checklist, the next steps happen in Kaui. + +From Aviate, use the *Billing Operations (Kaui)* links to open Kaui in a new tab. + +The following demo illustrates how you can switch to Kaui: +++++ +
+ +
+ +
+
+++++ + +'''' + +=== Create your first customer + +In Kaui: + +. Navigate to *Accounts*. +. Create a new account. +. Select the appropriate currency (EUR or GBP). +. Save the account. + +'''' + +The following demo illustrates the account creation process in Kaui: + + +++++ +
+ +
+ +
+
+++++ + +At this point, you have a customer but no billing activity yet. + +=== Create a subscription + +Next, attach a subscription to the customer. + +. Open the customer account. +. Create a new subscription. +. Select one of the catalog plans you created in Aviate. +. Optionally add an add-on. +. Confirm the start date. + +Kill Bill immediately generates billing events based on the catalog rules. + +The following demo guides you through the subscription creation process in Kaui: + +++++ +
+ +
+ +
+
+++++ + +'''' + +=== View the invoice + +Once the subscription is active: + +. Navigate to *Invoices* in Kaui. +. Open the newly generated invoice. +. Review: + +* Currency +* Line items +* Tax calculation +* Total amount + +This invoice uses the configuration, colors, and the logo defined earlier in Aviate. + +The following demo illustrates verifying the generated invoice: +++++ +
+ +
+ +
+
+++++ + +'''' + +== What You Have Achieved + +By following this guide, you have: + +* Configured a complete billing environment using *Aviate*. +* Created a customer and subscription using *Kaui*. +* Generated a real invoice powered by *Kill Bill*. +* Understood the separation of concerns between: + ** *Kill Bill* (engine) + ** *Aviate* (configuration) + ** *Kaui* (operations) + +You now have a fully working fictive SaaS company ready for demos or experimentation. + +'''' + +== Next Steps + +From here, you can: + +* Add more products or plans. +* Experiment with upgrades, downgrades, and add-ons. +* Explore payments and refunds. +* Integrate Kill Bill APIs into your own application. + +This same flow applies to production environments. Only the data changes.