killbill · reshmabidikar · Oct 8, 2025 · Sep 18, 2025 · Sep 18, 2025 · Sep 18, 2025
diff --git a/.idea/misc.xml b/.idea/misc.xml
diff --git a/reports/README.md b/reports/README.md
diff --git a/reports/accounts_summary/README.md b/reports/accounts_summary/README.md
@@ -1,10 +1,10 @@
-# Accounts summary report
+# Accounts Summary Report
 
 Provides an account summary. Provides details like account balance, account status, currency, etc.
 
 The snapshot view is: `v_report_accounts_summary`
 
-## Pie chart configuration
+## Report Creation
 
 ```
 curl -v \
@@ -15,9 +15,15 @@ curl -v \
      -H 'Content-Type: application/json' \
      -d '{"reportName": "report_accounts_summary",
           "reportType": "TABLE",
-          "reportPrettyName": "Accounts summary",
+          "reportPrettyName": "Accounts Summary",
           "sourceTableName": "report_accounts_summary",
           "refreshProcedureName": "refresh_report_accounts_summary",
           "refreshFrequency": "HOURLY"}' \
      "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
 ```
+
+## Report UI:
+
+![accounts-summary.png](accounts-summary.png)
+
+
diff --git a/reports/accounts_summary/accounts-summary.png b/reports/accounts_summary/accounts-summary.png
diff --git a/...unts_summary/v_report_account_summary.ddl → ...nts_summary/v_report_accounts_summary.ddl b/...unts_summary/v_report_account_summary.ddl → ...nts_summary/v_report_accounts_summary.ddl
diff --git a/reports/active_by_product_term_monthly/README.md b/reports/active_by_product_term_monthly/README.md
@@ -0,0 +1,40 @@
+# Monthly Active Subscriptions Report
+
+Compute (at the end of each month) the total number of active subscriptions per product and billing period.
+
+The snapshot view is: `v_report_active_by_product_term_monthly`
+
+## Report Creation
+
+```
+curl -v \
+     -X POST \
+     -u admin:password \
+     -H "X-Killbill-ApiKey:bob" \
+     -H "X-Killbill-ApiSecret:lazar" \
+     -H 'Content-Type: application/json' \
+     -d '{"reportName": "report_active_by_product_term_monthly",
+          "reportType": "TIMELINE",
+          "reportPrettyName": "Monthly Active Subscriptions by Product Term",
+          "sourceTableName": "report_active_by_product_term_monthly",
+          "refreshProcedureName": "refresh_active_by_product_term_monthly",
+          "refreshFrequency": "HOURLY"}' \
+     "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
+```
+## Sample Data
+
+| tenant_record_id | day        | product_name | billing_period | count |
+|------------------|------------|--------------|----------------|-------|
+| 1                | 2025-08-31 | Gold         | MONTHLY        | 3     |
+| 2                | 2025-08-31 | Gold         | MONTHLY        | 1     |
+| 1                | 2025-08-31 | Gold         | ANNUAL         | 2     |
+| 2                | 2025-09-30 | Silver       | MONTHLY        | 4     |
+| 2                | 2025-09-30 | Gold         | QUARTERLY      | 1     |
+
+The first row in the above table indicates that on `2025-08-31` the `tenant_record_id=1` had 3 Monthly subscriptions for the `Gold` product.
+
+
+
+## Report UI:
+
+![monthly-active-subs-by-product-term.png](monthly-active-subs-by-product-term.png)
diff --git a/reports/active_by_product_term_monthly/monthly-active-subs-by-product-term.png b/reports/active_by_product_term_monthly/monthly-active-subs-by-product-term.png
diff --git a/...report_active_by_product_term_monthly.ddl → ...report_active_by_product_term_monthly.ddl b/...report_active_by_product_term_monthly.ddl → ...report_active_by_product_term_monthly.ddl
@@ -11,27 +11,7 @@ DECLARE EXIT HANDLER FOR SQLWARNING ROLLBACK;
 SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED;
 START TRANSACTION;
   delete from report_active_by_product_term_monthly;
-  insert into report_active_by_product_term_monthly
-  select
-    x.tenant_record_id
-  , cal.d day
-  , x.product_name
-  , x.billing_period
-  , x.count
-  from calendar cal
-  join (
-    select
-      tenant_record_id
-    , last_day(day) day
-    , product_name
-    , billing_period
-    , count
-    from
-      v_report_active_by_product_term_monthly
-    where 1=1
-  ) x on last_day(cal.d) = x.day
-  where 1=1
-  ;
+  insert into report_active_by_product_term_monthly select * from v_report_active_by_product_term_monthly;
 COMMIT;
 
 END;

diff --git a/...report_active_by_product_term_monthly.ddl → ...report_active_by_product_term_monthly.ddl b/...report_active_by_product_term_monthly.ddl → ...report_active_by_product_term_monthly.ddl
diff --git a/reports/bundles_summary/README.md b/reports/bundles_summary/README.md
@@ -4,7 +4,7 @@ Provides a subscription bundle summary. Provides details like CTD, plan name, pr
 
 The snapshot view is: `v_report_bundles_summary`
 
-## Pie chart configuration
+## Report Creation
 
 ```
 curl -v \
@@ -15,9 +15,13 @@ curl -v \
      -H 'Content-Type: application/json' \
      -d '{"reportName": "report_bundles_summary",
           "reportType": "TABLE",
-          "reportPrettyName": "Bundles summary",
+          "reportPrettyName": "Bundles Summary",
           "sourceTableName": "report_bundles_summary",
           "refreshProcedureName": "refresh_report_bundles_summary",
           "refreshFrequency": "HOURLY"}' \
      "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
 ```
+
+## Report UI:
+
+![bundles-summary.png](bundles-summary.png)
diff --git a/reports/bundles_summary/bundles-summary.png b/reports/bundles_summary/bundles-summary.png
diff --git a/reports/cancellations_daily/README.md b/reports/cancellations_daily/README.md
@@ -0,0 +1,39 @@
+# Daily Cancellations Report
+
+Compute the total number of cancellations per day per phase.
+
+The snapshot view is: `v_report_cancellations_daily`
+
+## Report Creation
+
+```
+curl -v \
+     -X POST \
+     -u admin:password \
+     -H "X-Killbill-ApiKey:bob" \
+     -H "X-Killbill-ApiSecret:lazar" \
+     -H 'Content-Type: application/json' \
+     -d '{"reportName": "report_cancellations_daily",
+          "reportType": "TIMELINE",
+          "reportPrettyName": "Daily Cancellations",
+          "sourceTableName": "report_cancellations_daily",
+          "refreshProcedureName": "refresh_report_cancellations_daily",
+          "refreshFrequency": "HOURLY"}' \
+     "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
+```
+## Sample Data
+
+| tenant_record_id | phase     | day        | count |
+|------------------|-----------|------------|-------|
+| 1                | EVERGREEN | 2025-09-10 | 9     |
+| 1                | EVERGREEN | 2025-09-03 | 2     |
+| 1                | EVERGREEN | 2025-09-22 | 5     |
+| 2                | EVERGREEN | 2025-09-23 | 6     |
+| 2                | EVERGREEN | 2025-09-24 | 6     |
+| 1                | EVERGREEN | 2025-09-25 | 1     |
+
+The first row in the above table indicates that on `2025-09-10`, the `tenant_record_id=1` had 9 cancellations in `EVERGREEN` phase.
+
+## Report UI:
+
+![daily-cancellations.png](daily-cancellations.png)
diff --git a/reports/cancellations_daily/daily-cancellations.png b/reports/cancellations_daily/daily-cancellations.png
diff --git a/...ions_daily/report_cancellations_daily.ddl → ...ions_daily/report_cancellations_daily.ddl b/...ions_daily/report_cancellations_daily.ddl → ...ions_daily/report_cancellations_daily.ddl
diff --git a/...ns_daily/v_report_cancellations_daily.ddl → ...ns_daily/v_report_cancellations_daily.ddl b/...ns_daily/v_report_cancellations_daily.ddl → ...ns_daily/v_report_cancellations_daily.ddl
diff --git a/reports/chargebacks_daily/README.md b/reports/chargebacks_daily/README.md
@@ -0,0 +1,40 @@
+# Daily Chargebacks Report
+
+Compute the total value (in the reference currency) of chargebacks per day per currency.
+
+The snapshot view is: `v_report_chargebacks_daily`
+
+## Report Creation
+
+```
+curl -v \
+     -X POST \
+     -u admin:password \
+     -H "X-Killbill-ApiKey:bob" \
+     -H "X-Killbill-ApiSecret:lazar" \
+     -H 'Content-Type: application/json' \
+     -d '{"reportName": "report_chargebacks_daily",
+          "reportType": "TIMELINE",
+          "reportPrettyName": "Daily Chargebacks Value",
+          "sourceTableName": "report_chargebacks_daily",
+          "refreshProcedureName": "refresh_report_chargebacks_daily",
+          "refreshFrequency": "HOURLY"}' \
+     "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
+```
+
+## Sample Data
+
+| tenant_record_id | day        | currency | count    |
+|------------------|------------|----------|----------|
+| 1                | 2025-09-18 | USD      | 100.0000 |
+| 1                | 2025-09-26 | USD      | 50.0000  |
+| 2                | 2025-09-11 | USD      | 100.0000 |
+
+The first row in the above table indicates that on `2025-09-18`, the `tenant_record_id=1` had a total chargeback value of `$100`
+
+
+## Report UI:
+
+![chargebacks-daily.png](chargebacks-daily.png)
+
+
diff --git a/reports/chargebacks_daily/chargebacks-daily.png b/reports/chargebacks_daily/chargebacks-daily.png
diff --git a/...ebacks_daily/report_chargebacks_daily.ddl → ...ebacks_daily/report_chargebacks_daily.ddl b/...ebacks_daily/report_chargebacks_daily.ddl → ...ebacks_daily/report_chargebacks_daily.ddl
diff --git a/...acks_daily/v_report_chargebacks_daily.ddl → ...acks_daily/v_report_chargebacks_daily.ddl b/...acks_daily/v_report_chargebacks_daily.ddl → ...acks_daily/v_report_chargebacks_daily.ddl
@@ -3,7 +3,7 @@ select
   ac.tenant_record_id
 , date_format(ac.created_date,'%Y-%m-%d') as day
 , ac.currency
-, sum(ac.converted_amount) as count
+, sum(ac.amount) as count
 from
   analytics_payment_chargebacks ac
 where 1=1

diff --git a/reports/churn/README.md b/reports/churn/README.md
@@ -0,0 +1,54 @@
+# Churn (Monthly and Annual) Report
+
+This report tracks customer churn in dollar terms, showing both the total churned revenue and the churn percentage for monthly and annual subscriptions on a per-tenant, per-month basis.
+
+The snapshot view is: `v_report_churn_percent_and_total_usd`
+
+## Database Indices
+
+The churn reports requires some additional database indices to be created. See [churn-indices.ddl](churn-indices.ddl)
+
+## Churn Percent Configuration
+
+```
+curl -v \
+     -X POST \
+     -u admin:password \
+     -H "X-Killbill-ApiKey:bob" \
+     -H "X-Killbill-ApiSecret:lazar" \
+     -H 'Content-Type: application/json' \
+     -d '{"reportName": "report_churn_percent",
+          "reportType": "TIMELINE",
+          "reportPrettyName": "Churn Percent (Monthly and Annual)",
+          "sourceTableName": "report_churn_percent",
+          "refreshProcedureName": "refresh_report_churn_percent",
+          "refreshFrequency": "HOURLY"}' \
+     "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
+```
+
+## Churn Percentage Report UI
+
+![churn-percent.png.png](churn-percent.png)
+
+## Churn Amount Configuration
+
+```
+curl -v \
+     -X POST \
+     -u admin:password \
+     -H "X-Killbill-ApiKey:bob" \
+     -H "X-Killbill-ApiSecret:lazar" \
+     -H 'Content-Type: application/json' \
+     -d '{"reportName": "report_churn_total_usd",
+          "reportType": "TIMELINE",
+          "reportPrettyName": "Churn Total USD (Monthly and Annual)",
+          "sourceTableName": "report_churn_total_usd",
+          "refreshProcedureName": "refresh_report_churn_total_usd",
+          "refreshFrequency": "DAILY"}' \
+     "http://127.0.0.1:8080/plugins/killbill-analytics/reports"
+```
+
+## Churn Amount Report UI
+
+
+![churn-amount.png](churn-amount.png)
diff --git a/reports/churn/churn-amount.png b/reports/churn/churn-amount.png
diff --git a/reports/churn/churn-indices.ddl b/reports/churn/churn-indices.ddl
@@ -0,0 +1,4 @@
+CREATE INDEX idx_ai_tenant_bundle ON analytics_invoice_items(tenant_record_id, bundle_id, invoice_original_amount_charged, invoice_balance);
+CREATE INDEX idx_ast_bundle_tenant_event ON analytics_subscription_transitions(bundle_id, tenant_record_id, event, next_start_date, next_end_date, next_billing_period);
+CREATE INDEX idx_subs_id_tenant ON subscriptions(id, tenant_record_id);
+CREATE INDEX idx_se_sub_tenant_type ON subscription_events(subscription_id, tenant_record_id, user_type);
diff --git a/reports/churn/churn-percent.png b/reports/churn/churn-percent.png
diff --git a/reports/churn/report_churn_percent.ddl b/reports/churn/report_churn_percent.ddl
@@ -0,0 +1,21 @@
+create table report_churn_percent as select tenant_record_id
+   , month day, billing_period, churn_pct count from v_report_churn_percent_and_total_usd limit 0;
+
+drop procedure if exists refresh_report_churn_percent;
+DELIMITER //
+CREATE PROCEDURE refresh_report_churn_percent()
+BEGIN
+
+DECLARE EXIT HANDLER FOR SQLEXCEPTION ROLLBACK;
+DECLARE EXIT HANDLER FOR SQLWARNING ROLLBACK;
+
+SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED;
+START TRANSACTION;
+  delete from report_churn_percent;
+  insert into report_churn_percent select tenant_record_id
+                                              , month day, billing_period, churn_pct count from v_report_churn_percent_and_total_usd;
+COMMIT;
+
+END;
+//
+DELIMITER ;
diff --git a/reports/churn/report_churn_total_usd.ddl b/reports/churn/report_churn_total_usd.ddl
@@ -0,0 +1,21 @@
+create table report_churn_total_usd as select tenant_record_id
+   , month day, billing_period, churn_dollars count from v_report_churn_percent_and_total_usd limit 0;
+
+drop procedure if exists refresh_report_churn_total_usd;
+DELIMITER //
+CREATE PROCEDURE refresh_report_churn_total_usd()
+BEGIN
+
+DECLARE EXIT HANDLER FOR SQLEXCEPTION ROLLBACK;
+DECLARE EXIT HANDLER FOR SQLWARNING ROLLBACK;
+
+SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED;
+START TRANSACTION;
+  delete from report_churn_total_usd;
+  insert into report_churn_total_usd select tenant_record_id
+                                              , month day, billing_period, churn_dollars count from v_report_churn_percent_and_total_usd;
+COMMIT;
+
+END;
+//
+DELIMITER ;