​
Define a Billable metric

Usage events are designed to target very specific Billable metrics created from the UI. If you don’t understand the concept of Billable metrics, we recommend you to read it first.

First things first, you need to define a Billable metric from the UI to send usage measurement events:

  1. In the Lago App, go to the Billable metrics section
  2. Click on the Add a Billable metric button
  3. Fill the Billable metric informations.
    • A name
    • A code (this is used as the event name when ingesting measurement events)
    • A description (optional)
  4. Choose the Aggregation type to define how ingested events must be calculated at the end of the billable period
  5. Define if this metric is recurring or not.

A Billable metric must be representative of a paying feature of your company. Based on your customers’ actions within your application, implemented events are automatically triggered, aggregated and calculated by Lago.

​
Send usage measurements to Lago

To send usage events to Lago, you need to use the Lago API. A measurement event is JSON with the following fields:

{
  "external_customer_id": "__CUSTOMER_ID__", // (Required) Unique identifier of your customer performing the action
  "external_subscription_id": "__SUBSCRIPTION_ID__" // (Optional) Required only in case of multiple plans for a single customer
  "code": "__EVENT_CODE__", // (Required) Your Billable metric's Code
  "timestamp": 1650893379, // (Required) UNIX Timestamp when the event happened
  "properties": {
    "custom_field": 12, // (Optional) Custom variables defined as properties
    "operation_type": "add" or "remove" // (Optional) Required only for recurring metric with unique count aggregation type
  }
}

​
Idempotency and retries

By using a unique transaction_id, can send events to Lago as much as you want without worrying about sending twice the same event. Duplicates will be ignored by our system. This ensures that your customers’ usage is counted once. In case of duplicates, we guarantee that only one of the events will be ingested, and the other ones are ignored.

In case you are not sure if an event has been ingested, we recommend you to send it multiple times (or to replay it). Once again, with the uniqueness of the transaction_id, your customers won’t be badly affected.

​
User action trigger or periodic trigger

With Lago, you can define when you need to trigger events based on the actions your customers make in your application. There are 2 ways of tracking billing events with Lago.

​
User action trigger

Anytime a user perform an action in your product, this sends an event to Lago. This can be useful for companies tracking usage with a lot of granularity. As we do the math for you, you can send events whenever you need and don’t compute hard calculations on your own.

For instance, think of a fintech company tracking user action. Each time a customer withdraw money at an ATM, you send an event to Lago. We aggregate the usage of a billable period based on what you defined in a Billable metric called atm_withdrawals.

​
Periodic trigger

Some companies, such as infrastructure or cloud ones, often use periodic triggers to calculate consumption. Think of the example of a thermometer to measure fever. We would probably track the temperature once per hour (at a periodic time). This is the same for cloud companies selling computation. You could send an event to Lago each single minute measuring the CPU consumption of a customer.

​
Designed for flexibility

Lago is designed to ingest a high number of events. By defining aggregation rules, you can define any billing use cases your company might want to track. Whether you need to send user action triggered events or periodic triggered events, Lago does the math on your own so you don’t have to query heavy databases before charging your customers.

​
Next steps

Once you defined your Billable metrics (with their aggregation rules), and started ingesting events to track usage, you are able to define how much your customers will pay for it. This has to be specified in Plans.