POST /usage_events

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.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Valid values: `"all-disabled"`
`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-event-actions`	String	No	skip all actions to be done on the events Valid values: `"all-disabled"`
`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.
`chargebee-event-email`	String	No	skip only emails Valid values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`usage_timestamp`	Integer	Yes	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`	Object	Yes	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: There is a size limit of 1 KB. Learn more about field naming guidelines.
`deduplication_id`	String	Yes	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`	String	Yes	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.

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.