Introducing the Better Auth Chargebee plugin: Use it to handle subscriptions, billing, and auth seamlessly.
Chargebeechargebee API

Retrieve usage summary for a subscription

Retrieves aggregated usage data for a metered feature in a subscription over a specified reporting window.

Unlike Retrieve Current Usage Charges for a Subscription API, which returns the current unbilled usage snapshot including charges, this endpoint returns aggregated usage for a requested timeframe.

Use this endpoint to power experiences such as:

  • plotting daily, weekly, or monthly usage trends
  • analyzing feature adoption over time
  • comparing recent usage against earlier periods
  • showing historical usage summaries to subscribers

What this endpoint returns

Returns usage summary entries for the requested feature within the specified timeframe.

If timeframe_start and timeframe_end are not provided, the reporting range defaults to the start of the subscription's current term for timeframe_start and the current time for timeframe_end.

How aggregation works

  • If window_size is omitted, the response returns a single aggregate for the full reporting range.
  • If window_size is provided, the response returns one aggregated entry for each window in the reporting range.

Aggregation windows begin at timeframe_start and continue consecutively until timeframe_end.

The usages in the window will be bucketed into rolling windows aligned to timeframe_start, not to calendar boundaries.

Example

If:

  • timeframe_start is May 10 10:00:00 UTC
  • timeframe_end is June 10 10:00:00 UTC
  • window_size is day

The response returns windows such as:

  • May 10 10:00:00 UTC → May 11 10:00:00 UTC
  • May 11 10:00:00 UTC → May 12 10:00:00 UTC

and continues in the same pattern until the final window:

  • June 9 10:00:00 UTC → June 10 10:00:00 UTC

If you need calendar-aligned reporting, set timeframe_start to the required boundary. For example, use 00:00:00 UTC for daily reporting aligned to calendar days, or the first day of the month at 00:00:00 UTC for monthly reporting aligned to calendar months.

Each aggregation window follows inclusive-exclusive semantics:

  • aggregated_from is inclusive
  • aggregated_till is exclusive

In other words, each window is represented as aggregated_from and aggregated_till.

This means:

  • an event with a timestamp exactly equal to aggregated_from is included in that window
  • an event with a timestamp exactly equal to aggregated_till is excluded from that window and counted in the next window, if one exists
  • an event with a timestamp exactly equal to timeframe_end is excluded

These inclusive-exclusive boundaries ensure that windows do not overlap and that events on boundaries are never double-counted.

Sample Request

Retrieve usage summary for a subscription

Sample Result[JSON]

URL Format

GET https://[site].chargebee.com/api/v2/subscriptions/{subscription-id}/usage_summary

Input Parameters

limit
optional, integer, default=10, min=1, max=100

The number of resources to be returned.

offset
optional, string, max chars=1000

Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.

feature_id
required, string, max chars=100

Unique identifier of the metered feature for which usage is aggregated

window_size
optional, enumerated string

Specifies the aggregation interval for the reporting window. If omitted, the response includes a single aggregate for the entire reporting window.

Enum Values
month
week
day
hour
minute
timeframe_start
optional, timestamp(UTC) in seconds

Start of the reporting window, in Unix epoch seconds. If not provided, defaults to the start of the current subscription term.

timeframe_end
optional, timestamp(UTC) in seconds

End of the reporting window, in Unix epoch seconds. If not provided, defaults to the current time

Returns

next_offset
optional, string, max chars=1000

This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter offset.

usage_summary
Usage summary object
Resource object representing usage_summary