📚 How to Choose Between BILLSUMMARY and PLANCHANGEVOICE for Plan Cost Display

docs/general/how-to-choose-between-billsummary-and-planchangevoice-for-pl.md

@@ -0,0 +1,151 @@
+# How to Choose Between `BILLSUMMARY` and `PLANCHANGEVOICE` for Plan Cost Display
+
+## Overview
+
+This guide explains when to use the `BILLSUMMARY` data source versus `PLANCHANGEVOICE` when displaying a customer’s plan cost, especially for users who have recently switched plans.
+
+## Prerequisites
+
+- Understanding of the billing domain, including:
+  - What constitutes a “billing cycle”
+  - How mid-cycle plan changes and prorated charges work
+- Access to:
+  - `BILLSUMMARY` (billing summary data source)
+  - `PLANCHANGEVOICE` (plan change/voice billing data source)
+- Clarity on the product requirement: whether you need to show:
+  - The **current plan’s recurring cost**, or
+  - The **actual charges for the current billing cycle**, including prorations
+
+## Explanation: When to Use Each Data Source
+
+### 1. Using `BILLSUMMARY`
+
+**Primary use case:** Displaying the customer’s **current plan cost** (i.e., the standard recurring amount for their active plan), regardless of recent plan changes.
+
+- `BILLSUMMARY` is expected to:
+  - Always hold the **current plan cost**
+  - Be consistent even if the user **recently switched plans**
+- Recommended default:
+  - If your goal is to show “What is my plan and how much does it cost per period?” use `BILLSUMMARY` for all users.
+  - This avoids special-case logic for users who recently changed plans.
+
+### 2. Using `PLANCHANGEVOICE`
+
+**Primary use case:** Handling **mid-cycle plan changes** where prorated charges apply and you need to reflect those changes accurately.
+
+- `PLANCHANGEVOICE` is relevant when:
+  - A user **switched plans mid-billing-cycle**
+  - You need to understand or display **prorated charges** or detailed plan-change line items
+- However, for a simple “plan cost” display:
+  - Using `PLANCHANGEVOICE` can introduce complexity and risk of showing **partial** or **misleading** amounts if interpreted as the full plan cost.
+
+### 3. Why Not Always Show Prorated Charges?
+
+- If a user changed plans mid-cycle, the actual charges on the bill may be **prorated**.
+- Showing prorated amounts as if they were the full recurring plan cost would be:
+  - **Inaccurate** for representing the ongoing plan price
+  - **Misleading** to the user (“fraction of what they pay” this cycle vs. standard recurring cost)
+- For clarity and user trust, the UI should:
+  - Use `BILLSUMMARY` to show the **standard recurring plan cost**
+  - Reserve prorated details for a **billing details** or **invoice breakdown** view, if needed.
+
+## Recommended Approach
+
+1. **Default to `BILLSUMMARY` for plan cost display**
+   - Use `BILLSUMMARY` as the single source of truth for:
+     - Current plan name
+     - Current plan recurring cost
+   - Apply this consistently for:
+     - Users who have not changed plans
+     - Users who have recently changed plans
+
+2. **Use `PLANCHANGEVOICE` only for detailed billing views**
+   - If you need to:
+     - Show a breakdown of mid-cycle plan changes
+     - Explain why a bill includes partial charges for multiple plans
+   - Then query `PLANCHANGEVOICE` in a **billing details** context, not in the main “plan cost” display.
+
+3. **Avoid mixing prorated charges into the “plan cost” UI**
+   - Do not display prorated amounts as the plan’s recurring price.
+   - Clearly separate:
+     - “Your plan costs $X per month” (from `BILLSUMMARY`)
+     - “This month’s charges include prorated amounts” (from `PLANCHANGEVOICE` or invoice-level data)
+
+## Important Notes and Caveats
+
+- **Assumption about `BILLSUMMARY`:**  
+  The guidance above assumes:
+  - `BILLSUMMARY` always reflects the **current active plan’s full recurring cost**, even if the plan was changed recently.
+  - It does **not** include prorated mid-cycle adjustments as the primary “plan cost” value.
+- **Complexity trade-off:**  
+  Introducing conditional logic (e.g., “if user recently changed plans, use `PLANCHANGEVOICE` instead”) significantly increases complexity and risk of inconsistent or misleading displays.
+- **User expectations:**  
+  Users typically expect:
+  - A stable, easy-to-understand “plan price”
+  - Separate, detailed explanations for any unusual or prorated charges
+
+## Troubleshooting
+
+### Issue 1: Displayed plan cost looks too low for users who recently changed plans
+
+**Possible cause:**
+- Using prorated charges (from `PLANCHANGEVOICE` or invoice line items) as the plan cost.
+
+**Resolution:**
+- Switch the plan cost display to use `BILLSUMMARY` exclusively.
+- Reserve prorated amounts for a detailed billing breakdown.
+
+---
+
+### Issue 2: Need to explain why the bill shows multiple or partial charges
+
+**Possible cause:**
+- User switched plans mid-billing-cycle, generating prorated charges.
+
+**Resolution:**
+1. Use `PLANCHANGEVOICE` (and/or invoice-level data) to:
+   - Identify the old and new plans
+   - Determine the dates of the plan change
+   - List prorated charges for each plan segment
+2. Present this in a **billing details** or **invoice explanation** view, not as the main plan cost.
+
+---
+
+### Issue 3: Unclear which field in `BILLSUMMARY` is the “current plan cost”
+
+**Possible cause:**
+- Schema or field naming is not documented or standardized.
+
+**Resolution:**
+- Confirm with the billing or data engineering team:
+  - Which field in `BILLSUMMARY` is the authoritative “current recurring plan cost”
+  - Whether that field is guaranteed to be populated and accurate after a recent plan change
+- Update this guide with:
+  - The exact field name(s)
+  - Any edge cases (e.g., trial periods, discounts, or promotions)
+
+## Additional Information Needed (Open Questions)
+
+To finalize this guidance, the following should be clarified and documented:
+
+1. **Exact schema details:**
+   - Field names in `BILLSUMMARY` for:
+     - Current plan identifier
+     - Current recurring plan cost
+   - Field names in `PLANCHANGEVOICE` for:
+     - Old vs. new plan
+     - Effective dates
+     - Prorated amounts
+
+2. **Timing guarantees:**
+   - How quickly `BILLSUMMARY` is updated after a plan change
+   - Whether there are any known delays or edge cases
+
+3. **Special cases:**
+   - How free trials, discounts, or promotional pricing are represented in `BILLSUMMARY`
+   - Whether any customers might not have a valid `BILLSUMMARY` record
+
+Once these details are confirmed, they should be added to this document to make it a complete implementation reference.
+
+---
+*Source: [Original Slack thread](https://distylai.slack.com/archives/impl-tower-sales/p1765390529592749)*