# Usage charges

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


Usage charge represents the current, unbilled usage for a metered feature in a subscription within its active usage period. Each usage charge reflects usage accumulated from the start of the current usage period up to the time of the request. It includes:

-   the metered feature (`feature_id`)
-   the included entitlement for the current period (`included_usage`)
-   the total usage recorded so far (`total_usage`)
-   any chargeable usage beyond the included entitlement, including on-demand usage and amount (`on_demand_usage`, `metered_item_price_id`, `amount`)
-   the usage interval (`usage_from`, `usage_to`) used to compute the usage

## Sample Usage charge

```json
{
  "usage_charge": {
    "subscription_id": "__test__AzqPdGTCnPXT7FXQ",
    "feature_id": "API-Requests",
    "included_usage": "150",
    "total_usage": "3398.0",
    "on_demand_usage": "3248.0",
    "metered_item_price_id": "API-Requests-Addon-USD-Weekly",
    "amount": "812",
    "currency_code": "USD",
    "usage_from": 1756116026,
    "usage_to": 1756733467,
    "object": "usage_charge"
  }
}
```

## Usage charges attributes

## Input Parameters

- `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](/docs/api/features/feature-object#id) for which usage is tracked.

- `included_usage` (optional, string, max chars=33)
  Usage included in the [subscription entitlement](/docs/api/subscription_entitlements/subscription-entitlement-object) 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 the feature has an associated metered addon.

- `metered_item_price_id` (optional, string, max chars=100)
  Identifier of the metered [item price](/docs/api/item_prices/item-price-object) used to calculate charges. Returned only when the feature has an associated metered addon.

- `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 the feature has an associated metered addon.

- `currency_code` (optional, string, max chars=3)
  ISO [currency code](/docs/api/currencies/currency-object#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](/docs/api/usage_charges/usage-charge-object#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](/docs/api/usage_charges/usage-charge-object#total_usage) for the feature.