Using AI coding agents like Claude Code or Cursor? Try the official Chargebee Agent Skills to speed up your development.Try now
ChargebeeAPI

Usage charges

Usage charges expose the current, unbilled usage charges for metered features in a subscription during its ongoing usage period. Use this resource to track how much usage a subscription has accumulated so far and to understand any usage that exceeds the included entitlement.

A usage charge is calculated per metered feature and reflects usage recorded from the start of the current usage period up to the present.

Each usage charge includes:

  • The metered feature being measured (feature_id)
  • The usage included as part of the subscription entitlement for the current period (included_usage)
  • The total usage accumulated so far in the current period (total_usage)
  • Details of chargeable usage beyond the included limit, such as on-demand usage, pricing, and charge amount (on_demand_usage, metered_item_price_id, and amount)
  • The usage window (usage_from and usage_to) used to compute the accumulated usage

Sample Usage chargeJSON

API Index URL

https://[site].chargebee.com/api/v2/usage_charges

Usage charges attributes

subscription_id
required, string, max chars=100

Unique identifier of the subscription to which the usage charge applies.

feature_id
required, string, max chars=100

Unique identifier of the feature for which usage is tracked.

included_usage
optional, string, max chars=33

Usage included in the subscription entitlement for the current usage period.

total_usage
optional, string, max chars=33

Total usage accumulated so far for the feature in the current usage period.

on_demand_usage
optional, string, max chars=33

Usage beyond the included entitlement for the current usage period. Returned only when overages exist.

metered_item_price_id
optional, string, max chars=100

Identifier of the metered item price used to calculate overage charges. Returned only when amount exists.

amount
optional, string, max chars=39

Current overage charge computed from usage recorded so far, in major units of the currency. This value can change until the usage period ends. Returned only when amount exists.

currency_code
optional, string, max chars=3

ISO currency code in which the overage charges are computed. Returned only when amount exists.

usage_from
required, timestamp(UTC) in seconds

Start timestamp of the usage window used to compute the accumulated total_usage for the feature.

usage_to
required, timestamp(UTC) in seconds

End timestamp of the usage window used to compute the accumulated total_usage for the feature.