GET /subscriptions/{subscription-id}/usage_charges

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.

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

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

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

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

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

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

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

screenshot|/images/retrieve_usage_charges_for_subscription_1.png

Response Behaviour

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

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

"list": [
        "usage_charge": {
            "subscription_id":"sub-001",
            "feature_id": "storage_abc",
            ���usage_from���:"1 Jan 00:00:00", // For readability, the exact dates are shown here; the actual response will have timestamps.
            ���usage_to���:"16 Jan 08:59:59",
            "included_usage": "100",
            "total_usage": "80",
            "on_demand_usage": "0",              
            "amount": "0",
            "metered_item_price_id":"storage_001"
          },
        "usage_charge": {
            "subscription_id":"sub-001",
            "feature_id": "storage_abc",
            ���usage_from���:"16 Jan 09:00:00",
            ���usage_to���:"20 Jan 23:59:59",
            "included_usage": "220",
            "total_usage": "100",
            "on_demand_usage": "0",                  
            "amount": "0",
            "metered_item_price_id":"storage_001"
          }
  ]

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

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

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

Name	Type	Required	Description
`limit`	Integer	No	The number of resources to be returned. Default value: 10
`feature_id`	Object	No	optional, string filter Unique identifier of the metered feature for which usage is tracked. Supported operators : is Example → feature_id[is] = "fea-user-licenses"
`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.

limit

Integer

No

The number of resources to be returned.

Default value: 10

feature_id

Object

No

optional, string filter

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

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

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.

All third party trademarks (including logos and icons) are the property of their respective owners, which do not sponsor, authorize, or endorse this website.

Pricing Templates Integrations Blog Contact Us Help

Terms of Service Privacy Policy