# Usage events

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


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](/docs/api/usage_events/create-a-usage-event) for individual events and [Ingest Usage Events in Batch](/docs/api/usage_events/ingest-usages-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](/docs/api/entitlements), [items](/docs/api/items)(such as plans or addons), or [item prices](/docs/api/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.

**Note** :- [Learn more](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/usage-based-billing-usecases) about the use cases associated with this resource.

-   [Learn more](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/understanding-usages) about the Usage-based Billing.
-   [Learn more](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/ingesting-usage-from-amazon-s3) about ingesting usage events from Amazon S3.

**See also**

-   [Limits for Usage-based Billing in Chargebee](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/understanding-usages#usage-based-billing-limits)

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

## Usage events attributes

## Input Parameters

- `subscription_id` (required, string, max chars=50)
  The unique identifier of a subscription.

- `deduplication_id` (required, string, max chars=36)
  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`.

- `usage_timestamp` (required, long)
  The timestamp indicating when this usage occurred, represented as [Epoch](https://en.wikipedia.org/wiki/Unix_time) time in **milliseconds** . Example: `1738732394123` represents the timestamp for February 5, 2025, at 05:13:14.123 UTC.
  
  **Note**: The timestamp must be within the last **12 hours** .

- `properties` (required, jsonobject)
  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 `string` values such as `accepted` or `processing` in one context.
      
  -   In another scenario, it might hold numeric values, such as HTTP response codes like `200`, `300`, or `400`.
      
  
  **Note**:
  
  -   Learn more about [field naming guidelines](/docs/api/usage_files).