Settings
Configure SDK
Usage events
This resource allows you to record usage events, which are essential for usage-based billing. These events track customer consumption and calculate charges based on actual usage. You can send usage data to Chargebee using two endpoints: Ingest a Usage Event for individual events and Ingest Usage Events in Batch for bulk submissions.
The usage event resource payload is schema-less, providing the flexibility to adapt to your unique business requirements. Because usage events are not directly tied to a pricing plan, this resource enables independent tracking of feature consumption. Events are processed and associated with relevant features as usage data. This information is used for billing alongside entitlements, items(such as plans or addons), or item prices to generate invoices. This decoupling of usage data from the product catalog provides flexibility in defining and monetizing usage beyond predefined pricing models. Additionally, this API supports feature usage analytics, churn prediction, and other insights.
- Learn more about the use cases associated with this resource.
- Learn more about the Usage-based Billing.
Sample usage event [ JSON ]
{
"usage_timestamp": "179506024062",
"subscription_id": "SUB-1",
"deduplication_id": "usage-301513005",
"properties": {
"input_tokens": 1100,
"output_tokens": 7400,
"token_ratio": 6.73,
"model_name": "gpt-3.5",
"prompt_type": "code_completion",
"temperature": 0.6,
"top_p": 0.85,
"frequency_penalty": 0.4,
"presence_penalty": 0.15,
"fine_tuned": false,
"response_time_ms": 180,
"completion_success_rate_percent": 99.1,
"api_endpoints": "generateCompletion",
"cpu_usage_percent": 65,
"memory_usage_mb": 2200,
"webhook_events_sent": 45
}
}API Index URL GET
An identifier used by the Chargebee's customer to distinguish between multiple events generated at the same timestamp for a single subscription_id.
The combination of usage_timestamp, subscription_id, and deduplication_id uniquely identifies each event.
Example:
If 3 events are generated for subscription_id = sub-1 at 2025-04-01T00:00:00.000Z, each event must have a distinct deduplication_id.
The timestamp indicating when this usage occurred, represented as Epoch time in milliseconds.
Example:
1738732394123 represents the timestamp for February 5, 2025, at 05:13:14.123 UTC. A schema-less field that accepts any JSON-formatted data to define the attributes of the ingested event. It is a requirement to structure the data in a flat format wherever possible for better compatibility with downstream processing.
We strongly encourage using unique field names—particularly for fields intended for metering purposes. This approach enhances clarity and maintainability in the future.
For example, a field named status,
-
Can represent
stringvalues such asacceptedorprocessingin one context. -
In another scenario, it might hold numeric values, such as HTTP response codes like
200,300, or400.
Ingest a usage event ¶
This endpoint ingests a usage event into Chargebee.
A single event can be of 1 KB in size.
Limit: 10,000 events per minute.
Sample Response [ JSON ]
URL Format POST
Input Parameters
An identifier used by the Chargebee's customer to distinguish between multiple events generated at the same timestamp for a single subscription_id.
The combination of usage_timestamp, subscription_id, and deduplication_id uniquely identifies each event.
Example:
If 3 events are generated for subscription_id = sub-1 at 2025-04-01T00:00:00.000Z, each event must have a distinct deduplication_id.
The unique identifier of a subscription.
- If an existing
subscription_idis provided, usage data is recorded against it. - If the subscription does not exist yet in Chargebee, a new
subscription_idcan be used, and the subscription can be imported later, once the usage is successfully recorded. - During invoice generation, recorded usage linked to the
subscription_idwill be applied to the invoice.
The timestamp indicating when this usage occurred, represented as Epoch time in milliseconds.
Example:
1738732394123 represents the timestamp for February 5, 2025, at 05:13:14.123 UTC. A schema-less field that accepts any JSON-formatted data to define the attributes of the ingested event. It is a requirement to structure the data in a flat format wherever possible for better compatibility with downstream processing.
We strongly encourage using unique field names—particularly for fields intended for metering purposes. This approach enhances clarity and maintainability in the future.
For example, a field named status,
-
Can represent
stringvalues such asacceptedorprocessingin one context. -
In another scenario, it might hold numeric values, such as HTTP response codes like
200,300, or400.
Returns
Resource object representing usage_event
Ingest usage events in batch ¶
This endpoint ingests a batch of usage events into Chargebee.
You can ingest 500 events in a batch ingestion, each 1 KB in size. This means a single API request will efficiently handle 500 KB of data.
Limit: 10,000 events per minute.
Sample Response [ JSON ]
URL Format POST
Input Parameters
pass parameters as events[{<param name> : <value>,<param name> : <value> ...}]
Returns
The unique identifier for the batch of usage events processed.
A detailed list of events that failed during the batch ingestion process.