# Retrieve usage charges for a subscription

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


[Eventually Consistent](/docs/api/read-consistency)

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.

Read more about time concepts

### 1\. Subscription current term[](#1-subscription-current-term)

The **subscription current term** is the broader billing term of the subscription. It is usually determined by the lowest-frequency item on the subscription, typically the plan.

It is included as context only.

This endpoint does not return usage for the full subscription term unless that also happens to be the feature’s active usage window.

### 2\. Current usage period[](#2-current-usage-period)

The **current usage period** is the time range in which usage is actively accruing and has not yet been billed for a feature.

This is the primary time window used by the API.

How it is determined

**Feature with metered addon -** The current usage period is the overage addon’s billing period.

**Feature without metered addon -** The current usage period is the currently active entitlement window for that feature.

### 3\. Usage intervals[](#3-usage-intervals)

A **current usage period** may be returned as a single interval or as multiple intervals.

A **usage interval** is a continuous segment where the feature’s entitlement and pricing remain unchanged.

If nothing changes during the period, the API returns one entry for that feature.

If something changes, the API returns multiple entries for the same feature.

#### Changes that can create multiple intervals[](#changes-that-can-create-multiple-intervals)

-   Entitlement changes mid-period
-   A metered addon is added, removed, or expires
-   Overage pricing changes mid-period
-   Pricing configuration changes during the active period

Read more about example scenario

### Example Scenario[](#example-scenario)

-   **Base Plan:** Includes 100 GB/month (Starts 1 Jan).
-   **Mid-Period Change: Addon #1** (+200 GB/month) is added on **16 Jan 09:00:00**
-   **Snapshot Date:** API is called on **20 Jan.**

**Current Usage Period: 1 Jan 00:00:00 – 31 Jan 23:59:59**

#### Usage Interval 1: 1 Jan 00:00:00 – 16 Jan 08:59:59[](#usage-interval-1-1-jan-000000-16-jan-085959)

This interval reflects the subscription’s state before the addon was active.

-   **Entitlement:** 100 GB (Base Plan)
-   **Usage:** 80 GB consumed
-   **Carry-forward:** The remaining 20 GB of the base plan is carried into the next interval.

#### Usage Interval 2: 16 Jan 09:00:00 – 20 Jan 23:59:59[](#usage-interval-2-16-jan-090000-20-jan-235959)

This interval begins the moment the entitlement context changes and ends at the response snapshot (20 Jan).

-   **Entitlement:** 220 GB total
    -   _Calculation: 20 GB (remaining from Base Plan) + 200 GB (Addon #1)_
-   **Usage:** 100 GB consumed during this specific 4-day window.
-   **Note:** Although the billing month ends on 31 Jan, the `usage_to` date is capped at the snapshot date (Jan 20).

![use case example](/images/retrieve_usage_charges_for_subscription_1.png)

#### Response Behaviour[](#response-behaviour)

The API returns separate usage charge objects for each interval where entitlement remains stable.

1.  **First object - Initial Plan Period**
    
    Covers the storage feature from **1 Jan 00:00:00** to **16 Jan 08:59:59**.
    
    During this interval, total entitlement is **100 GB**.
    
    **80 GB** is consumed, so **20 GB** remains and carries forward into the next interval.
    
2.  **Second object - Post-Addon Addition**
    
    -   Covers the storage feature from **16 Jan 09:00:00** to **20 Jan 23:59:59**.
    -   During this interval, total entitlement is **220 GB**, calculated as:
        -   **200 GB** from Addon #1
        -   **20 GB** carried forward from the plan
    -   **100 GB** is consumed out of 220 GB; hence, no charges.

##### **Response for Jan 20**[](#response-for-jan-20)

**Note:** For readability, the example above uses dates such as `1 Jan` and `16 Jan`. In the actual API response, `usage_from` and `usage_to` are returned as timestamps.

## Integration notes[](#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

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdv6kOj/usage_charges \
     -u {site_api_key}:
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;

ApiConfig.Configure("{site}","{site_api_key}");
ListResult result = UsageCharge.RetrieveUsageChargesForSubscription("__test__8asukSOXdv6kOj").Request();

foreach (var listItem in result.List){
  UsageCharge usageCharge = listItem.UsageCharge;
}
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    usagechargeAction "github.com/chargebee/chargebee-go/v3/actions/usagecharge"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := usagechargeAction.RetrieveUsageChargesForSubscription("__test__8asukSOXdv6kOj", nil).ListRequest()
    if err != nil {
        fmt.Println(err)
    } else {
        for idx := 0; idx < len(res.List); idx++ {
            UsageCharge := res.List[idx].UsageCharge
        }
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.UsageChargeRetrieveUsageChargesForSubscriptionRequest{}
  res, err := client.UsageCharge.RetrieveUsageChargesForSubscription("__test__8asukSOXdv6kOj", req)
      if err != nil {
        fmt.Println(err)
    } else {
        for idx := 0; idx < len(res.List); idx++ {
            UsageCharge := res.List[idx].UsageCharge
        }
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;
import java.util.List;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        ListResult result = UsageCharge.retrieveUsageChargesForSubscription("__test__8asukSOXdv6kOj").request();

        for (ListResult.Entry entry : result) {
            UsageCharge usageCharge = entry.usageCharge();
        }
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.usageCharge.UsageCharge;
import com.chargebee.v4.models.usageCharge.params.RetrieveUsageChargesForSubscriptionParams;
import com.chargebee.v4.models.usageCharge.responses.RetrieveUsageChargesForSubscriptionResponse;
import java.util.List;

public class RetrieveUsageChargesForSubscription {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        RetrieveUsageChargesForSubscriptionResponse response = client.usageCharges().retrieveUsageChargesForSubscription("__test__8asukSOXdv6kOj");
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.usageCharge.retrieveUsageChargesForSubscription("__test__8asukSOXdv6kOj");
    result.list.forEach((entry) => {
        console.log(entry);
        const usageCharge = entry.usage_charge;
    });
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->usageCharge()->retrieveUsageChargesForSubscription("__test__8asukSOXdv6kOj");
foreach($result->list as $entry) {
    $usageCharge = $entry->usage_charge;
}
```

#### Python

```python
from chargebee import Chargebee, Filters

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
entries = cb_client.UsageCharge.retrieve_usage_charges_for_subscription("__test__8asukSOXdv6kOj")
for entry in entries.list:
    usage_charge = entry.usage_charge
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

list = ChargeBee::UsageCharge.retrieve_usage_charges_for_subscription("__test__8asukSOXdv6kOj")

list.each do |entry|
  usage_charge = entry.usage_charge
end
```

## Sample Response

```json
{
  "list": [
    {
      "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"
      }
    },
    {..}
  ]
}
```

## 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.

## 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`