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

Retrieve usage charges for a subscription

Returns the current, unbilled usage charges for the metered features on a subscription.

This endpoint returns usage for each feature’s current usage period. If entitlement or pricing changes during that period, the same feature can appear multiple times, with one usage_charge object returned for each interval.

Use this endpoint to present the below information in your portal or customer-facing experiences.

  • current usage to date
  • included entitlement
  • on-demand or overage usage, if any
  • the current chargeable amount, when applicable

This endpoint does not return historical, billed, or invoice-backed usage.

This endpoint returns usage for the active usage window of each feature, not necessarily for the full subscription term.

To read the response correctly, keep these three concepts in mind:

  • Subscription current term: The overall billing term of the subscription, usually defined by the plan.
  • Current usage period: The active period for which usage is currently accruing and has not yet been billed for a feature.
  • Usage interval: A continuous segment within the current usage period where entitlement and pricing remain unchanged.

Integration notes

When processing the response:

  • Group entries by feature_id
  • Sort intervals by usage_from
  • Do not assume one entry per feature
  • Use amount only when present
  • Treat the response as a snapshot of current unbilled usage

Sample Request

Sample Result[JSON]

URL Format

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

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.

Filter Params

For operator usages, see the Pagination and Filtering section.
feature_id[<operator>]

optional, string filter

Unique identifier of the metered feature for which usage is tracked. Supported operators : is

Example → feature_id[is] = "fea-user-licenses"

Supported operators: is
Example → feat_123

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_charge
Usage charge object
Resource object representing usage_charge