Skip to main content

​
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
  }
}
The transaction_id is very useful to ensure the uniqueness of the events received. It is mandatory to define on your own a unique transaction_id for each event you send to Lago.This identifier is used to deduplicate events ingested, making sure we don’t ingest twice the same event (otherwise, this could create billing errors for your customers).
  • If a transaction_id is new to Lago, the event is ingested;
  • If a transaction_id has already been received by Lago, it’s ignored and API will return a 422: "Unprocessable Entity"
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
Good practice: Send the id of the transaction coming from your backend. If you do not have an existing id for a transaction, you can create a unique one by concatenating the code of the Billable metric and the timestamp of the event *(example: api_searches_2022-04-01T03:49:23Z).
This attribute allows Lago to assign the event to the right subscription (and therefore to the right customer). The external subscription_id is required, as it ensures accurate billing.
The event code represents the unique code of the Billable metric you want to start ingest measurements on. This code is required for all events received in Lago. For instance, you can start ingesting events for Billable metrics with codes api_seaches (for api products example), storage (cloud companies example), atm_withdrawals (fintech example), or anything you need to define as a paying feature.
The event timestamp is the date when the billing event occurs in your application and sent to Lago. This event must be a UNIX Timestamp. For instance, you could define 1650893379 for Mon Apr 25 2022 13:29:39 GMT+0000 or 1651682217for Wed May 04 2022 16:36:57 GMT+0000.You can ingest usage event in seconds or milliseconds. (more information about the timestamp here)This timestamp is not mandatory to send the event. If you do not specify a timestamp on your own, Lago automatically defines the reception date of the event as the event timestamp.
The event’s precise amount in cents refers to the amount sent to Lago when using a dynamic charge model. This value must be specified in cents.The precise_total_amount_cents is not mandatory when sending the event. If you do not specify an amount, Lago will automatically set it to 0, and the event will not be included in the charge aggregation.
Event properties are useful to send more context in usage events. Moreover, they are also very useful when you need to aggregate a Billable metrics for SUM, MAX and UNIQUE COUNT. Event properties can be strings, integers, floats, uuids or timestamps.In case of an aggregation type UNIQUE COUNT for a metric that is recurring , the operation_type is required. By sending add, you will add a value. By sending remove, you will remove a value.
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.
⌘I