​
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 “Add a billable metric”;
  3. Add metric information, including:
    • name
    • code (used to send events via API)
    • description (optional)
  4. Define whether or not this metric is recurring; and
  5. Choose an aggregation type to define how usage should be calculated.

Billable metrics represent the features of your product. Events should automatically be sent to Lago by your application based on your customers’ actions.

​
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:

{
  "transaction_id": "__TRANSACTION_ID__", // (Required) Unique identifier of the event
  "external_subscription_id": "__SUBSCRIPTION_ID__", // (Required) Unique identifier of your customer's subscription
  "code": "__EVENT_CODE__", // (Required) The billable metric's code
  "timestamp": 1650893379, // (Optional) UNIX timestamp of the event
  "precise_total_amount_cents": "140", // (Optional) Precise amount cents of the event used for dynamic charge model
  "properties": {
    "custom_field": 12, // (Optional) Custom variables defined as properties
    "operation_type": "add" or "remove" // (Optional) Required only for recurring metric based on the unique count aggregation
  }
}

If you were using the external_customer_id to send usage measurement, note that this field is deprecated and is no longer supported or maintained. Please use the external_subscription_id instead.

​
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.

If your Lago’s organization is configured to use the new Clickhouse-based event pipeline (designed for high-volume processing), the idempotency logic is handled differently.

Event uniqueness is maintained with both transaction_id and timestamp fields:

  • If transaction_id and timestamp are new to Lago, the event is ingested;
  • If transaction_id and timestamp have already been received by Lago, the event will replace the previous one

​
Event timestamp

We typically log usage-based events using timestamps in seconds, such as 1741219251, which represents the number of seconds since January 1, 1970 (the Unix epoch).

However, when higher precision is required, you can also use a timestamp with millisecond accuracy in the format 1741219251.590. Here, the dot acts as the decimal separator, clearly distinguishing the whole seconds from the fractional milliseconds (590 ms in the previous example).

This format minimizes ambiguity and ensures consistency when sending usage-based events.

​
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.

​
Batching events

In Lago, event batching allows for the efficient ingestion of multiple events through a single API call. This capability enhances data throughput and reduces the number of API requests needed for event management.

  • Batching multiple events: Users can aggregate multiple events into a single batch. This consolidation enables the ingestion of numerous events simultaneously, significantly optimizing the data transmission process.
  • API call limitation: Lago supports batching of up to 100 events per API call. This feature is designed to balance between high-volume data handling and system performance.
  • Validation process: If any event within the batch does not meet the structural requirements, the entire batch will be rejected. This ensures data integrity and consistency. Users are advised to verify the structure of each event before batching to prevent rejections.

​
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.