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

List usages

Advanced Usage-Based Billing

For high-scale usage ingestion, use Advanced Usage-Based Billing with the Usage Events API. The Usage Events API supports schemaless event ingestion at scale, including individual events, batch ingestion, and usage file ingestion.

Retrieves the list of usages. This endpoint is part of the Usages API for Automated Metered Billing.

Sample Request

List usages

Sample Result[JSON]

URL Format

GET https://[site].chargebee.com/api/v2/usages

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.

sort_by[<sort-order>]
optional, object

optional, string filter

Sorts based on the specified attribute. Supported attributes : usage_date

Supported sort-orders : asc, desc

Example → sort_by[asc] = "usage_date"

This will sort the result based on the 'usage_date' attribute in ascending(earliest first) order.

Filter Params

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

optional, string filter

A unique and immutable id for the usage. If not provided, it is autogenerated. Supported operators : is, is_not, starts_with

Example → id[is] = "usage_lsfja24411"

Supported operators: is, is_not, starts_with
Example → usage_lsfja24411
subscription_id[<operator>]

optional, string filter

The id of the subscription to which this usage record belongs. Supported operators : is, is_not, starts_with

Example → subscription_id[is] = "active2"

Supported operators: is, is_not, starts_with
Example → active2
usage_date[<operator>]

optional, timestamp(UTC) in seconds filter

The time at which this usage occurred. Chargebee bills only those usages whose usage_date falls within a time when the subscription status was active or non_renewing. However, the remaining usage records are still stored and are retrievable.

Note: If usage_date corresponds to a time already invoiced, then it is stored but never invoiced unless the invoice is regenerated . Supported operators : after, before, on, between

Example → usage_date[after] = "1601220958"

Supported operators: after, before, on, between
Example → 1601220958
updated_at[<operator>]
Supported operators: after, before, on, between
Example → 1601220958
item_price_id[<operator>]

optional, string filter

The id of the item price to which this usage belongs. The item price must be a part of the subscription or should have been part of it historically. Supported operators : is, is_not, starts_with

Example → item_price_id[is] = "sprout"

Supported operators: is, is_not, starts_with
Example → sprout
invoice_id[<operator>]

optional, string filter

When the usage has been invoiced, this is the id of the invoice. This is cleared when the invoice is voided or deleted. Supported operators : is, is_not, starts_with, is_present

Example → invoice_id[is] = "null"

Supported operators: is, is_not, starts_with, is_present
source[<operator>]

optional, enumerated string filter

The source from which the usage record was created. Possible values are : admin_console, api, bulk_operation.

Supported operators : is, is_not, in, not_in

Example → source[is] = "api"

Supported operators: is, is_not, in, not_in
Example → api

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
Usage object
Resource object representing usage