Build a real-time customer usage dashboard with Chargebee
Your customers are on a usage-based plan. They deserve to see exactly what they’re consuming, in real time, inside your product, before the invoice arrives. This recipe shows you how to build that, end to end, with Chargebee’s Usage APIs.
Usage-based pricing creates a new obligation: real-time visibility for your customers.
AI agents, automation platforms, developer tools, the products that run on usage-based models today can burn through a monthly allocation in hours. The invoice is no longer a reasonable place to find out what something cost.
When a customer’s bill is tied to what they consume, the dashboard is part of the product contract. The questions it must answer aren’t optional:
- “How much of my entitlement have I used, and how much is left?”
- “Am I in overage, and what is it costing me right now?”
- “Is my usage this month normal, or is something accelerating?”
- “What will my next invoice actually look like?”
Four APIs. Each answers one customer question.
Used together, they take a customer from “what did I buy?” to “what will I pay next?” in a single page load.
Your customer’s plan, billing period, quota, and which features are tracked for usage. Everything else on the dashboard is built on top of this.
How much they’ve used, how much was included in their plan, and what they’ve gone over, broken down per feature, updated in real time.
Usage rolled up by day, week, or month. Answers whether this month is tracking above or below their usual pattern.
A live preview of the next invoice, every charge, including overages, before the billing cycle closes. Turns the dashboard from informational to financially useful.
What did they buy? Set the commercial frame first.
Before showing any usage number, the dashboard needs to know the plan, the quota, and which items are metered. One API call gives you all three.
- Plan
- Zapier Team
- Billing cycle
- Annual
- Term start
- Jun 1 2025
- Term end / renewal
- Jun 1 2026
// Response (abbreviated) { "subscription": { "id": "sub_Hs7pNorthwind", "status": "active", "current_term_start": 1748736000, "current_term_end": 1780272000, // Jun 1 2026 "next_billing_at": 1780272000, "subscription_items": [ { "item_price_id": "zapier-team-annual", "item_type": "plan", "amount": 2638800, "metered": false // flat ─ no usage card }, { "item_price_id": "tasks-overage-monthly", "item_type": "addon", "metered": true // ← render usage card } ] } }
How much have they used? And how much is already in overage?
One call. Everything you need for usage cards, progress bars, and the overage alert, consumed, included, overage quantity, and overage amount.
// Response (abbreviated) { "usage": [{ "subscription_id": "sub_Hs7pNorthwind", "feature_id": "tasks_automated", "feature_name": "Tasks Automated", "feature_unit": "task", "consumed_quantity": 820000, "entitled_quantity": 750000, "overage_quantity": 70000, "overage_unit_price": 0.02, "overage_amount": 1400.00, "item_tiers": [...] }] }
How is usage changing? Context turns a number into a story.
820K tasks consumed is noise without history. Set window_size=month and you get monthly buckets, enough to see that usage spiked in September when a new integration went live, and has been accelerating since.
| Month | Tasks | vs pool | Overage | Amount |
|---|---|---|---|---|
| Jun–Oct 2025 | 1,320,000 | Within | — | — |
| Nov 2025 | 780,000 | +30K | 30,000 | $600 |
| Dec 2025 | 820,000 | +70K | 70,000 | $1,400 |
// Query params ?window_size=month &timeframe_start=2025-06-01 &timeframe_end=2025-12-31 &feature_id=tasks_automated // Response — one row per window { "usage_summaries": [ { "feature_id": "tasks_automated", "feature_unit": "task", "consumed_quantity": 780000, // Nov "aggregated_from": "2025-11-01", "aggregated_till": "2025-11-30" }, { "feature_id": "tasks_automated", "consumed_quantity": 820000, // Dec "aggregated_from": "2025-12-01", "aggregated_till": "2025-12-31" } // ... one object per month ] }
What will they be charged? Show them before it posts.
Called with include_usages=true, the Upcoming Invoice Estimate returns a real-time invoice preview. The line_item_usages[] array links every charge back to the feature that caused it.
// Query params ?include_usages=true &invoicing_strategy=current_term_end // Response (key fields) { "invoice_estimate": { "line_items": [ { "description": "Zapier Team - annual", "amount": 2638800 }, { "description": "tasks_automated overage", "amount": 140000, "metered": true } ], "line_item_usages": [{ "feature_id": "tasks_automated", "consumed_quantity": 820000, "entitled_quantity": 750000, "overage_quantity": 70000, "overage_amount": 1400.00 }] } }
Metering tracks what happened. Billing knows what it means.
Any metering system can count API calls. What it can’t tell you is whether those calls are within entitlement, which tier they fall into, what the overage rate is, and what the next invoice will say. That’s not a metering problem, it’s a billing problem. Chargebee sits at the intersection.
consumed_quantity vs entitled_quantity is computed against your subscription’s commercial terms, not a raw counter. The entitlement boundary is the billing system’s job to know. Transparency turns customers into advocates.
When customers see exactly what they're consuming and paying for, trust goes up and disputes go down. Chargebee's Usage APIs surface real-time consumption, entitlements, and invoice previews so your dashboard shows the truth. Customers who see value stay. You build it once and it stays correct as plans change.