GET /subscriptions/{subscription-id}/usage_summary

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.

Distinct-count behavior

If a feature uses distinct-count aggregation, the distinct count is evaluated separately within each returned window.

This means the same entity can be counted once in multiple windows if it appears in each of them.

Example

If the same user appears in both:

one daily window on Jan 1
another daily window on Jan 2

That user is counted once in the Jan 1 aggregate and once in the Jan 2 aggregate.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Path parameters

Name	Type	Required	Description
`subscription-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.

Query parameters

Name	Type	Required	Description
`limit`	Integer	No	The number of resources to be returned. Default value: 10
`window_size`	String	No	Specifies the aggregation interval for the reporting window. If omitted, the response includes a single aggregate for the entire reporting window. * day - Aggregates usage by day. * minute - Aggregates usage by minute. * hour - Aggregates usage by hour. * month - Aggregates usage by month. * week - Aggregates usage by week. Valid values: `"month"` `"day"` `"week"` `"minute"` `"hour"`
`timeframe_end`	Integer	No	End of the reporting window, in Unix epoch seconds. If not provided, defaults to the current time
`timeframe_start`	Integer	No	Start of the reporting window, in Unix epoch seconds. If not provided, defaults to the start of the current subscription term.
`feature_id`	String	Yes	Unique identifier of the metered feature for which usage is aggregated
`offset`	String	No	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.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.