📚 How to Retrieve Plan Charges Using the bill_with_deltas_and_ch_lookup API Tool

docs/general/how-to-retrieve-plan-charges-using-the-bill-with-deltas-and-.md

@@ -0,0 +1,139 @@
+# How to Retrieve Plan Charges Using the `bill_with_deltas_and_ch_lookup` API Tool
+
+## Overview
+
+This guide explains which API tool to use and how to retrieve a customer’s plan charges (including monthly amount and charge-level details) using the `bill_with_deltas_and_ch_lookup` tool, as well as how this relates to other APIs for obtaining the plan name.
+
+## Prerequisites
+
+- Access to the **BFF Bill Summary** service (Backend-for-Frontend bill summary API).
+- Ability to call internal **CH tools** (Charge History or Charge Handling tools, depending on your internal terminology).
+- Access to any **other APIs** used to retrieve the customer’s **plan name/title** (since plan name may not always be available directly from this tool).
+- Authentication/authorization credentials required by your internal APIs.
+
+> Note: Specific endpoint URLs, authentication schemes, and request/response schemas are not provided in the Slack discussion and must be obtained from your internal API documentation.
+
+## Explanation and Usage
+
+### 1. Select the Correct Tool
+
+To retrieve detailed plan charges and related charge history:
+
+- Use the **`bill_with_deltas_and_ch_lookup`** tool.
+- This tool is part of, or is called via, the **BFF Bill Summary** layer.
+
+This tool provides:
+
+- A breakdown of charges by category (e.g., plan charges).
+- Specific charge history (CH) entries you can leverage, such as:
+  - High-Speed Internet (HSI) plan changes.
+  - Mobile Internet (MI) rate plan changes.
+- Plan charges that are **always surfaced** with the new CHs enabled in the referenced release.
+
+### 2. Inputs to the API / Tool Call
+
+From the Slack context, the exact input schema is not specified. However, typical inputs for this type of tool would include:
+
+- **Customer identifier** (e.g., account ID, billing account number, or subscriber ID).
+- **Billing period** or statement date (if you need charges for a specific month).
+- **Context parameters** if you are injecting this into a routine or another tool (e.g., routine ID, session ID, or correlation ID).
+
+Because the Slack thread does not define the exact input fields, you will need to confirm:
+
+- Required path or query parameters (e.g., `/bill_with_deltas_and_ch_lookup?accountId={id}&billDate={date}`).
+- Required headers (e.g., `Authorization`, `X-Correlation-Id`).
+- Any optional filters (e.g., filter by charge type, product, or service).
+
+### 3. How to Call the CH Tool via the API
+
+The Slack discussion confirms that:
+
+- You should **call the `bill_with_deltas_and_ch_lookup` tool** when you need charge-level detail.
+- This tool can be **injected as context** into:
+  - A routine, or
+  - Another tool.
+
+A typical high-level call flow might look like:
+
+1. **Call BFF Bill Summary** with the customer and billing context.
+2. Within that call (or as a secondary call), invoke **`bill_with_deltas_and_ch_lookup`** with the same identifiers.
+3. Use the returned CH data to:
+   - Identify plan charges.
+   - Extract the **monthly amount** the user pays for their plan.
+   - Identify specific CH entries for HSI and MI plan/rate plan changes.
+
+> Since no concrete HTTP examples were provided, consult your internal API reference for:
+> - The exact endpoint for `bill_with_deltas_and_ch_lookup`.
+> - Whether it is a direct REST endpoint, a GraphQL field, or an internal tool call within an orchestration layer.
+
+### 4. Retrieving the Monthly Plan Amount vs. Plan Name
+
+From the Slack answers:
+
+- **Monthly plan amount**:
+  - “It’s always easy to get the amount they pay for their plan.”
+  - With the new CHs enabled, **plan charges will always be surfaced**.
+  - Therefore, you can reliably obtain the **monthly amount** from the output of `bill_with_deltas_and_ch_lookup`.
+
+- **Plan name/title**:
+  - There may not be a way to get the plan title in every case directly from this tool.
+  - However, “we can get the plan name of the user from other APIs.”
+  - Recommended approach:
+    1. Use `bill_with_deltas_and_ch_lookup` to get the **plan charge and amount**.
+    2. Use **another API** (e.g., product catalog, subscriber profile, or plan metadata API) to map the plan identifier to a **human-readable plan name**.
+
+## Important Notes and Caveats
+
+- **Plan charges availability**: With the new CHs enabled in the referenced release, **plan charges should always be present** in the tool’s response.
+- **Plan name completeness**: Do not assume the plan title is always available from the bill/CH tool alone. Design your integration to:
+  - Handle missing plan titles gracefully.
+  - Fallback to another API to resolve the plan name.
+- **Context injection**: The tool is intended to be used as context for:
+  - Routines (e.g., workflows or orchestrations).
+  - Other tools that may need billing or charge-level information.
+
+## Troubleshooting
+
+### Issue: Cannot Find the Monthly Amount for the Plan
+
+- **Symptoms**: The response appears to lack a clear “plan amount” field.
+- **Actions**:
+  - Verify you are calling **`bill_with_deltas_and_ch_lookup`**, not a less detailed bill summary endpoint.
+  - Check for a **plan charge line item** in the returned charge breakdown.
+  - Confirm that the **new CHs** (charge history enhancements) are enabled in your environment.
+
+### Issue: Plan Title/Name Is Missing
+
+- **Symptoms**: You can see the charge and amount, but no human-readable plan name.
+- **Actions**:
+  - Confirm whether the tool is expected to return plan titles in your environment.
+  - Use the **plan identifier** from the charge data to query:
+    - A **plan catalog API**, or
+    - A **subscriber profile / product metadata API**.
+  - Implement a fallback so that if the title is missing, you still show the amount and possibly a generic label (e.g., “Primary Plan”).
+
+### Issue: Unclear How to Call the CH Tool via API
+
+- **Symptoms**: You know you need `bill_with_deltas_and_ch_lookup` but do not know the endpoint or parameters.
+- **Actions**:
+  - Check your internal API documentation for:
+    - The **BFF Bill Summary** API specification.
+    - The **`bill_with_deltas_and_ch_lookup`** endpoint or schema.
+  - Confirm with your backend team:
+    - Whether it is exposed as a REST endpoint, GraphQL field, or internal tool call.
+    - The required **inputs** (account ID, bill date, etc.) and **authentication**.
+
+## Additional Information Needed
+
+To fully operationalize this guide, you will need to obtain the following from your internal documentation or backend team:
+
+- Exact **endpoint URL** or method name for `bill_with_deltas_and_ch_lookup`.
+- Full **request schema** (required and optional parameters).
+- Full **response schema**, including:
+  - Where plan charges are located.
+  - How to identify plan vs. non-plan charges.
+  - Any identifiers that can be used to look up the plan name.
+- Details of the **other APIs** used to retrieve the plan name/title.
+
+---
+*Source: [Original Slack thread](https://distylai.slack.com/archives/impl-tower-billing/p1763573474606089)*