This guide explains how Lago ingests usage-based events coming from your application.
name
code
(used to send events via API)description
(optional)recurring
; and1. The transaction_id
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).transaction_id
is new to Lago, the event is ingested;transaction_id
has already been received by Lago, it’s ignored and API will return a 422: "Unprocessable Entity"
transaction_id
and timestamp
fields:transaction_id
and timestamp
are new to Lago, the event is ingested;transaction_id
and timestamp
have already been received by Lago, the event will replace the previous onecode
of the Billable metric and the timestamp
of the
event *(example: api_searches_2022-04-01T03:49:23Z
).2. The external_subscription_id
external subscription_id
is required, as it ensures accurate billing.3. The event code
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
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
6. The event properties
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.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.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.
transaction_id
and timestamp
fields:transaction_id
and timestamp
are new to Lago, the event is ingested;transaction_id
and timestamp
have already been received by Lago, the event will replace the previous one1741219251
, 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.
atm_withdrawals
.