Merge pull request killbill#618 from killbill/aviate-coupons

aviate coupons doc

Author: sbrossie

html5/_main_toc.html.slim

@@ -368,6 +368,9 @@ nav.sidebar-nav
             li.bd-sidenav-active
               a.nav-link href="/latest/aviate-wallet.html"
                 | Wallet
+            li.bd-sidenav-active
+              a.nav-link href="/latest/aviate-coupons.html"
+                | Coupons
             li.bd-sidenav-active
               a.nav-link href="/latest/aviate-usage-ai-tutorial.html"
                 | Usage Tutorial (AI use case)

userguide/aviate/aviate-coupons.adoc

@@ -0,0 +1,62 @@
+= Aviate Coupons
+
+include::{sourcedir}/aviate/includes/aviate-card.adoc[]
+
+== Introduction
+
+The Aviate plugin enables the management of Coupons, i.e. reusable discounts that can be applied to subscriptions using a redemption code. A coupon can be redeemed by customers when creating or updating a subscription (for example, during an upgrade). 
+
+Coupons provide flexibility to offer fixed-amount or percentage-based discounts and can be scoped to specific plans. They are designed to improve customer acquisition, incentivize upgrades, or manage targeted promotions.
+
+Each coupon includes configurable attributes to control its behavior, such as reusability, discount type, and optional expiration.
+
+== Coupon Attributes
+
+A coupon in Aviate consists of the following attributes:
+
+* `Redemption code`: A unique code that customers can use to apply the discount.
+* `Reusability`: Whether the coupon can be applied multiple times by the same customer.
+* `Discount type`: The discount calculation method:
+** `Fixed`: Applies a fixed monetary amount.
+** `Percentage`: Applies a percentage-based discount.
+* `Discount price`: Amount and currency (valid when `Discount type = Fixed`).
+* `Discount percentage`: Percentage value (valid when `Discount type = Percentage`).
+* `Expiration date`: Optional date after which the coupon can no longer be redeemed.
+* `Plan list`: Optional list of plans for which the coupon is applicable.
+
+== Getting Started with Aviate Coupons
+
+This section provides a step-by-step guide to enable and use the Aviate Coupon functionality.
+
+=== Installing the Plugin
+
+Install the Aviate plugin as described in the https://docs.killbill.io/latest/how-to-install-the-aviate-plugin.html[How to Install the Aviate Plugin] guide.
+
+=== Enabling Aviate Coupons
+
+To enable coupon functionality in the Aviate plugin, start Kill Bill with the following system property:
+
+[source,bash]
+----
+com.killbill.billing.plugin.aviate.enableCouponsApis=true
+----
+
+For details on setting configuration properties, refer to the https://docs.killbill.io/latest/userguide_configuration.html[Kill Bill Configuration Guide].
+
+=== Using Coupon APIs
+
+Once the plugin is installed and coupon support is enabled, you can interact with the Aviate Coupons using its API. The API allows you to:
+
+* Create and manage coupons.
+* Define attributes such as redemption code, discount type, and expiration.
+* Redeem coupons during subscription creation or updates.
+
+Full API documentation is available at:
+https://apidocs.killbill.io/aviate-coupons[our API documentation].
+
+== Using the Coupon Functionality
+
+1. Create a coupon specifying its attributes, including the redemption code, discount type (fixed or percentage), amount or percentage, and optional expiration date.
+2. Optionally, restrict the coupon to specific plans using the `Plan list` attribute.
+3. Provide the redemption code to customers, who can apply it when creating or updating subscriptions.
+4. Monitor coupon usage via the API to track redemption patterns and performance.