From 5507cee51b358cd2de9c3e1bcf628ba23728b751 Mon Sep 17 00:00:00 2001 From: yenchiafeng Date: Thu, 11 Dec 2025 09:41:52 -0800 Subject: [PATCH] docs: Add How to Retrieve Plan Charges Using the `bill_with_deltas_and_ch_lookup` API Tool --- ...charges-using-the-bill-with-deltas-and-.md | 139 ++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 docs/general/how-to-retrieve-plan-charges-using-the-bill-with-deltas-and-.md diff --git a/docs/general/how-to-retrieve-plan-charges-using-the-bill-with-deltas-and-.md b/docs/general/how-to-retrieve-plan-charges-using-the-bill-with-deltas-and-.md new file mode 100644 index 0000000..5ef78cb --- /dev/null +++ b/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)*