Ingesting usage
This guide explains how Lago ingests usage-based events coming from your application.
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:
- In the Lago app, go to the “Billable metrics” section;
- Click “Add a billable metric”;
- Add metric information, including:
name
code
(used to send events via API)description
(optional)
- Define whether or not this metric is
recurring
; and - 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:
1. The transaction_id
1. The transaction_id
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 a422: "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
andtimestamp
are new to Lago, the event is ingested; - If
transaction_id
andtimestamp
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
).
2. The external_subscription_id
2. The external_subscription_id
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.
3. The event code
3. The event code
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.
4. The event timestamp
4. The event timestamp
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 1651682217
for
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.
5. The event precise amount cent
5. The event precise amount cent
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.
6. The event properties
6. The event properties
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
andtimestamp
are new to Lago, the event is ingested; - If
transaction_id
andtimestamp
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.