Events-Based Billing Overview

What is Events-Based Billing?

Events-Based Billing is an evolved form of metered billing that is based on data-rich events streamed in real-time from your system to Chargify.

These events can then be transformed, enriched, or analyzed to form the computed totals of usage charges billed to your customers.


Events are actions occurring in your system that you wish to track. They are represented as JSON objects.

Event Examples:

  • The API calls being made to your app
  • The SMS messages or phone calls processed by your service
  • The logins or pageviews of your users
Examples of events


Collections of similar events are called “streams”. You can think of a stream as a database table, where each entry in the table is an event. Events in a stream should have similar schemas, although that is not required. Each stream has its own API endpoint where you send events to Chargify in real-time as they happen in your system.

To learn more about how to architect your events and streams, check out our Event Data Modeling Guide.

The guide on Getting Data In explains how to create streams and work with the events API.


Metrics are values computed from the events in your streams. Some examples include:

  • Total number of API requests
  • Total duration in minutes of all phone calls
  • Average response time of API requests

Metrics can use one of the following types of analyses: count, sum, average, median, minimum, maximum, and percentile.

Metrics are how insight is extracted from events in order to track data of interest over time. A single stream can have many metrics.

The “Getting Data In” guide contains a section on Creating Metrics.

Billing on Events

Once you have streamed events and defined one or more metrics, you can bill for them! For this, you must create an Event-based component, which is a type newly introduced into the standard Chargify component system.

Event-based components are similar to other component types, in that you define the component parameters (such as name and taxability) and the pricing. For the event-based type of component, a metric must also be selected. The metric provides the quantity that will be billed each period for each subscription.

So, instead of reporting usage directly for each component (as you would with metered components), the usage is derived from analysis of your events.

The guide for Billing on Events details how to set up the components and configure your billing on events.

Analyzing Event Data

You are not required to bill for your events. You may choose to just send all of your events to Chargify for analysis and insights. You may even find that you want to change from billing on one event metric to another event metric entirely. When all of your event data lives in Chargify, changes like that become easy.

You may analyze your events using our graphs on the Metrics screen.


Event an action or occurrence that happens in your system that you represent as a packet of JSON data and report to Chargify.

Stream a collection of similar events, usually with a similar schema.

Metric a computation (e.g. count, sum, or average) against a stream of events to produce a numeric value of interest. Usually, metrics are plotted or observed over different timeframes and intervals to extract insights.

Data Store a collection of event streams analagous to a database. Chargify gives you a data store automatically when Events-Based Billing is enabled, but you can attach other data stores from supported partners.

Learn More