Ingesting Usage Events into Chargebee

Introduction

Chargebee Billing makes it easy to ingest and manage usage data for your products or services. You don't need to set up complex configurations or create metering in advance to start bringing in your usage data. Simply upload your data as-is, and then use it to enable usage-based billing or gain valuable insights.

Chargebee Billing is built to handle high-volume usage ingestion reliably, while giving you full visibility into how usage events are processed and consumed. It also supports:

• schemaless ingestion.
• up to 100 million usage events per month.
• throughput of up to 12,000 events per second.

Core Concepts for Usage Ingestion

Understanding the following concepts will help you ingest usage events accurately and avoid common errors.

• De-duplication ID Each usage event must include a de-duplication ID. A de-duplication ID is a unique identifier for a usage event that occurred within a subscription at a specific millisecond. Chargebee uses this ID to ensure that duplicate usage events are not recorded. For example, if two usage events occur for the same subscription at 2026-01-10T10:15:30.123, each event must have a unique de-duplication ID. If both events share the same ID, only one event is recorded.

• Usage Timestamp and Ingestion Timestamp Chargebee tracks both usage time and ingestion time in milliseconds.

Generating Timestamps for Testing: For testing or manual entry, you can use an epoch timestamp converter to generate timestamps in milliseconds. Ensure that the value you use is in milliseconds, and not seconds.

Ingesting Usage Events

Chargebee offers three straightforward methods to bring your usage events into the system:

• Using the Usage Events API
• Importing Usage Events in Bulk
• Adding Usages Manually via UI

These methods ensure you can bring in usage events efficiently and accurately, whether you prefer automation, bulk import, or manual entry.

Usage Events API

You can use the Usage events API resource to send your usage data to Chargebee Billing. It supports both individual and batch ingestion of usage events, accommodating your data as-is without requiring adherence to a specific schema. Regardless of your business type, you can easily send usage data for your products or services to Chargebee. This is a one-time setup with no ongoing maintenance required.

Importing Usage Events in Bulk

Chargebee Billing allows you to import usage events in bulk, making it easy to upload large volumes of usage data quickly and efficiently. This method is ideal for your business if you have accumulated historical usage data, or you need to process a significant volume of usage records at once using the application.

To import usage events in bulk, simply prepare your data in a supported file format, ensuring it includes required attributes such as:

• Deduplication ID
• Subscription ID
• Usage timestamp in milliseconds

Once your data file is ready, follow the steps below to import your usage events into Chargebee Billing:

1. Navigate to Usages > Usage Events > Add Usages. Select the Import .CSV file tab. Alternatively, you can click Settings > Import & Export Data > Choose a Bulk Operation in your Chargebee Billing site. Select Usages > Create a Usage and click Proceed.
2. Drag and drop your data file into the web interface, or click Browse to select your file and upload it. Click Review and import.
3. On the next screen, you can review your data and make changes if required. You can:
   • Click Edit Data to modify any values.
   • Click Add Column to add missing fields for the data.
   • Click Add Row to add more usage events.
4. Once you have reviewed the data, click Complete Import.

Your usage events data will get imported into your Chargebee Billing site. You can use the All Processed Events tab to view usage events that were successfully processed.

Chargebee Billing immediately allows you to filter the usage events based on the event details/properties with which they were imported. Click the Event_id to view the usage event record in detail. The usage event details can be viewed both in Properties and JSON format.

Usage events that were not imported are listed under the Failed Events tab along with the failure reason. You can correct the respective data and attempt to import them again.

Adding Usages Manually via UI

Chargebee Billing gives you the flexibility to manually add usage events for smaller datasets or to make quick updates directly within the application user interface. This method is particularly useful for you when you occasionally need to record usage data without relying on automated or bulk processes.

To add usage events manually in your Chargebee Billing site:

1. Click Usages > Usage Events > Add Usages. Select the Manually Enter Data tab.

   

2. On the Add Usage page, enter the required details such as the usage event identifier, timestamp, and quantity.

3. Click Save.

Your usage data gets recorded successfully.

You can now start tracking and managing usage data in a way that works best for your business.

Read Next