From 79aa4c8444613aae03c437b31b10f1731b197ed3 Mon Sep 17 00:00:00 2001 From: yenchiafeng Date: Thu, 11 Dec 2025 09:44:02 -0800 Subject: [PATCH] docs: Add How to Choose Between `BILLSUMMARY` and `PLANCHANGEVOICE` for Plan Cost Display --- ...-billsummary-and-planchangevoice-for-pl.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 docs/general/how-to-choose-between-billsummary-and-planchangevoice-for-pl.md diff --git a/docs/general/how-to-choose-between-billsummary-and-planchangevoice-for-pl.md b/docs/general/how-to-choose-between-billsummary-and-planchangevoice-for-pl.md new file mode 100644 index 0000000..9ff3973 --- /dev/null +++ b/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)*