ChargebeeAPI

Ingest a usage event

Try in API Explorer

This endpoint ingests a usage event into Chargebee.

Note : - A single event can be of 1 KB in size.

  • Limit: 10,000 events per minute.

Sample Request

URL Format

POST https://[site].chargebee.com/api/v2/usage_events

Input Parameters

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.

subscription_id
required, string, max chars=50

The unique identifier of a subscription.

Note:

  • If an existing subscription_id is provided, usage data is recorded against it.
  • If the subscription does not exist yet in Chargebee, a new subscription_id can be used, and the subscription can be imported later, once the usage is successfully recorded.
  • During invoice generation, recorded usage linked to the subscription_id will be applied to the invoice.
usage_timestamp
required, long

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.

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:

Returns

usage_eventUsage event object

Resource object representing usage_event