Break down usage by group-by attributes

Overview

A group-by attribute is an event attribute that you group a metered feature's usage by. When you add group-by attributes to a metered feature, Chargebee Billing reports the metered feature's total along with a breakdown of that total by the attributes that drive it, such as region, gpu_type, api_key, model, or project_id. Breakdowns are available in four places. Two help your own teams analyze consumption, and two let you show your customers where their usage comes from.

Group-by attributes affect reporting and presentation only. Included usage, overage, and on-demand charges are always calculated from the metered feature's overall total, not from the breakdown.

Before you can use breakdowns, Advanced Usage-Based Billing must be enabled on your site, and the metered feature must have at least one group-by attribute. To add group-by attributes and review the limits that apply, see Defining Metered Features.

Break down GPU hours by GPU type and region

Suppose you run a cloud graphics processing unit (GPU) platform and bill customers for the GPU hours they consume. You create a metered feature, GPU Hours, that aggregates usage as the Sum of hours and groups it by two attributes: gpu_type and region.

Over a billing period, a subscription records 1,000 GPU hours in total. With group-by attributes, Chargebee Billing breaks that total down as follows:

You can view the breakdown by one attribute or by both:

• By region: us-east is 700 and eu-west is 300.
• By gpu_type: H100 is 550 and A100 is 450.
• By gpu_type and region: H100 in us-east (400), H100 in eu-west (150), A100 in us-east (300), and A100 in eu-west (150).

View usage breakdowns

Usage breakdowns in Usage Insights

You can group usage by any group-by attribute in Chargebee Billing, and filter to specific values, such as region set to us-east. Use these reports to see which attributes drive consumption. For example, your support team can see which region or model caused a usage spike before replying to a customer, your finance team can review the top contributors before a renewal conversation, and your infrastructure team can plan capacity by region.

To open the report:

1. Go to Usages > Metered Features.
2. Open the metered feature.
3. In the Usage Trend section, click View Details.
4. Click Usage Insights > Top contributing combinations.

The Top contributing combinations table is available only for metered features with at least one group-by attribute. Select the attributes under Group by, and click Add filter to limit the rows. The table shows the top 1,000 combinations by usage. Click Export to get every combination. A missing or null value appears as NULL.

Usage breakdowns in Automatic Exports

Group-by attribute values are included in the metered feature usage datasets delivered through Automatic Exports. Your data team can use these values for custom analysis in a data warehouse or business intelligence tool.

Usage breakdowns in the Usage Summary API

Use the Usage Summary API to build an in-product usage dashboard or customer portal that shows your customers where their consumption comes from. An itemized view helps customers understand their charges and reduces the billing questions they send to your support team.

For example, suppose you run an AI platform that bills customers for the tokens their applications consume. Each customer has many projects and uses several models in different regions. You create a metered feature, Tokens, that aggregates usage as the Sum of tokens and groups it by project_id, region, and model. Your customers' admins can then see which projects, regions, and models drive their usage.

Depending on the attributes you group by, you can offer views such as:

To build a view like Usage by project, your backend looks up the customer's subscription and calls the Usage Summary API grouped by project_id. The response is paginated, so your backend follows next_offset and collects every page before it ranks the projects. Your portal then renders the results as a ranked table or a trend chart. You can narrow the view to specific projects for a team lead, and add a time window for trends.

For the Sum and Count aggregation methods, the project values add up to the metered feature total when the view includes every group and covers the full invoice period. In that case, your portal matches the usage on the customer's invoice. A view filtered to some projects, or a trend window shorter than the invoice period, shows only part of that total.

For a step-by-step walkthrough with examples, see Show usage breakdowns by group-by attribute in your customer portal.

You can also use the Usage Summary API to:

• Break down usage by one or more group-by attributes in a single call.
• Filter the breakdown to specific attribute values, such as only the projects a team lead manages.
• Return a single aggregate for a period, or a time series in minute, hour, day, week, or month windows for trend charts.
• Keep missing and empty values separate. The null group and the "" group are returned as distinct groups.

For parameters and examples, see Retrieve usage summary for a subscription.

Usage breakdowns in the Usage PDF API

Use the Usage PDF API to give customers an itemized usage log to read alongside an invoice. The PDF breaks usage down by the group-by attributes you choose, nested in the order you specify, so customers can see which attributes drove the total usage on the invoice. Because the PDF is customer-facing, include only the attributes you want customers to see.

For example, suppose you run an AI platform with a Tokens metered feature grouped by project_id, region, and model. Your customer portal can offer a Download usage report button next to each invoice, on the same Usage page as the dashboard. When a customer selects it, your backend generates a Usage PDF for that invoice, broken down by region and model. The customer reads it alongside the invoice to see which regions and models drove the total usage. The dashboard and the PDF use the same metered feature but different attributes: the dashboard groups by project_id, and the PDF groups by region and model.

For the Sum and Count aggregation methods, the usage across all lines, including the null and empty-string groups, adds up to the overall usage for the metered feature on the invoice, so the PDF reconciles with what the customer was charged for.

Group-by breakdowns appear only in Usage PDFs generated through the Usage PDF API. The default Usage PDF that is attached to invoices or downloaded from the Chargebee Self-Serve Portal shows usage by date.

In the PDF, usage from events that don't include an attribute, or that include it with a null value, is shown in the null group, displayed as a dash (—). For example, in a PDF broken down by model, usage from events without model appears under model: —. Usage from events with an empty string is shown in a separate group with no value after the attribute name (for example, model:).

For breakdown parameters, see Retrieve usages for an invoice as PDF.

How group-by breakdowns handle edge cases

How group-by attributes handle missing, null, and empty values

Grouping by an attribute does not filter out events that lack it. Every event that the metered feature counts is placed in a group, similar to how SQL GROUP BY treats missing values:

• If an event includes the attribute with a value, the event is grouped under that value.
• If an event does not include the attribute, or includes it with a null value, the event is grouped under null.
• If an event includes the attribute with an empty string, the event is grouped under "", separately from null.

For the GPU Hours metered feature grouped by region:

• An event with "region": "us-east" is grouped under us-east.
• An event without region, or with "region": null, is grouped under null.
• An event with "region": "" is grouped under "".

The same rule applies when none of your current usage events include the attribute. Usage events do not follow a fixed schema, so you can add a group-by attribute before your events start sending it. Until they do, that usage is reported under null.

Breakdowns after you add a group-by attribute to an existing metered feature

Breakdowns by a group-by attribute are available only for usage events ingested after you add the attribute to the metered feature. Usage ingested before that point is not grouped retroactively. It is reported under the null group for that attribute, the same way as an event that does not include the attribute.

How breakdown values reconcile with the metered feature total

For metered features that use Sum or Count, the breakdown values add up to the metered feature total. For Average, Min, Max, and Count Distinct, Chargebee Billing calculates each value within its own group, so the values do not necessarily add up to the total. In every case, billing uses the metered feature total, not the sum of the breakdown values.

For example, a metered feature that tracks Peak Concurrent GPUs as the Max of concurrent_gpus, grouped by region, might report:

The rows add up to 105, but the metered feature total is 60, because the total is the single highest reading across the subscription, not the sum of the regional peaks. Min and Average behave the same way.

Count Distinct works similarly. If a metered feature counts distinct user_id values grouped by region, a user who is active in both regions is counted once in each region's group but only once in the total.

For these aggregation methods, treat the breakdown as a per-group view rather than a split of the total.

Coming soon: use group-by attributes for variable pricing

Group-by attributes drive reporting and presentation. Soon, the same attributes that you break usage down by will also let you set variable prices, charging different rates per region, gpu_type, or any other attribute for metered addons and credit drawdowns. The group-by attributes you set up become the foundation for variable pricing, with no need to re-instrument your metered features.