Cards / Item Explanations

Item‑Level Explanations enhance the what is changed experience by allowing administrators to define custom explanations for individual bill items. Instead of relying only on generic messages such as “Charge Added” or “Charge Changed,” consumers now see clear, item‑specific explanations that explain why their bill changed. This improves transparency, maintains trust, and reduces billing‑related support queries while preserving fallback coverage for any unmapped items.

Key Concepts

• Tags: Tags are short labels (for example, “Changed”, “Increased”, “New”) displayed above the explanation on the consumer’s What’s Changed card.

  Tags help consumers quickly identify the type of change without reading the full explanation.

• Variables: Titles and descriptions can include system variables and custom variables. These dynamically insert context into explanations, such as amounts or changes. Common system variables include:

  • customer_name

  • amount

  • previous_amount

  • change_amount

For example, your usage increased by change_amount, resulting in a total of amount. For more details, refer to the Dynamic Content Variables section.

Cards / Item Explanations

In the Bill Explainer app, admins access item‑level explanations by opening Studio and navigating to Pages > What Changed > Card / Item Explanation. On first access, no item explanations are shown, and an informational message guides admins to enable bill items before adding content.

Use the Manage button to open What Changed Explanations, where you can enable or disable bill items using toggles. Once items are enabled, they appear in the Card / Item Explanation list. If a bill item is disabled, it is removed from the Card / Item Explanation list.

 Use the Manage button to return to the bill item (What Changed Explanation) selection page.

When an item is enabled, an arrow icon appears next to it within the What Changed Explanation page. Select this arrow to open the item’s use‑cases configuration page, where you can configure explanations for Increase, Decrease, Added, and Removed scenarios.

The Show only with description toggle filters the list to display only items with content already configured. Enabling this toggle only filters the list and does not enable items or create content; it only helps you quickly identify items with existing explanations.

Also, selecting an item from the Card / Item Explanation list opens its Use Cases configuration page.

Use Cases

Each bill item supports four predefined use cases: Increase, Decrease, Added, and Removed. For each case, admins can configure content for both single‑item and multiple‑item scenarios.

Tags  are short labels shown above the explanation on the customer’s What Changed card. You can select them from the existing list or create new ones, with only one tag allowed per use case.

If the required tag is not available in the list, a Create button appears. Select Create to generate the new tag, which is then automatically selected for the use case.

Titles and Descriptions can include system variables and custom variables to dynamically insert contextual data, such as amounts, previous values, or change values, into explanations. This structure ensures consistent messaging while supporting flexible, item‑specific explanations.

The microsite displays a dedicated card with the configured item‑level explanation shown beneath the amount. The card design is consistent with existing section‑level explanations to maintain a seamless experience.

Fallback Behaviour

When multiple explanations could apply, the system follows this precedence order:

• Use Case level - explanation configured for the specific scenario (Increase, Decrease, Added, Removed)

• Bill Item level - general explanation configured for the bill item

• Section level - explanation defined at the section level

• Generic fallback - default system-generated message

The system always selects the highest applicable rule in this chain. If no custom explanation is configured at any level, default messages such as “State Tax Added,” “Charge Increased,” or “Charge Decreased” are shown.

This ensures complete coverage while allowing more specific configurations to override general ones.

Troubleshooting

• Why your custom explanation may not appear

  If your configured explanation is not displayed on an item, it is usually due to precedence rules. Check the following:

  • A higher-precedence rule is applied

    A Use Case–level explanation overrides Bill Item, Section, and fallback explanations. If a different use case configuration exists, it will take priority.

  • The item is not enabled

    Ensure the bill item is enabled in the What’s Changed Explanations (Manage) section. Disabled items do not display configured explanations.

  • The explanation is not configured for the specific scenario

    Verify that content is added for the correct use case (Increase, Decrease, Added, or Removed).

  • Fallback is being used

    If no configuration exists at any level, the system displays the default fallback message.

Key Benefits

• Improved Explainability: Show clear, item‑specific reasons for every bill change instead of generic fallback messages.

• Reduced Support Calls: Help customers understand charge changes instantly, lowering billing‑related inquiries.

• Admin‑Controlled Messaging: Configure and manage item‑level explanations directly in Studio without engineering effort.

• Consistent Coverage with Fallback: Ensure every bill item always displays an explanation, even when custom text is not configured.

• Brand‑Aligned Communication: Customize titles and descriptions to match your brand voice while retaining productized defaults.

• Better Customer Trust: Provide transparency into late fees, usage, adjustments, promos, and other common charges to build confidence.