Skip to main content

Metered events

Events represents the data delivered to lago application that will then be aggregated into billable metrics. By sending a metered event, it's not persisted through the next billable periods. At the end of each period, the total units to be charged is resumed to 0. Metered events are available for all billable metrics having the following aggregation type: COUNT, SUM, MAX and COUNT_UNIQUE.

The following endpoint explains how to send a metered event for a customer.





curl --location --request POST "$LAGO_URL/api/v1/events" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"event": {
"transaction_id": "__UNIQUE_ID__",
"external_customer_id": "__YOUR_CUSTOMER_ID__",
"external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
"code": "__EVENT_CODE__",
"timestamp": $(date +%s),
"properties": {
"custom_field": 12


"event": {
"transaction_id": "__UNIQUE_ID__",
"external_customer_id": "__CUSTOMER_ID__",
"external_subscription_id": "__SUBSCRIPTION_ID__",
"code": "__EVENT_CODE__",
"timestamp": 1650893379,
"properties": {
"custom_field": 12
transaction_idString      RequiredUnique ID identifying the event.
As it will be used for idempotency, it should be a unique identifier
external_subscription_idString      OptionalUnique subscription ID in your application.
external_subscription_id is required if the customer has multiple subscriptions or if external_customer_id is not provided (in case there's only one subscription)
external_customer_idString      OptionalUnique customer ID in your application.
If external_subscription_id is not given, external_customer_id is required if there is only one subscription attached to customer. For multiple subscriptions per customer this attribute is not enough
codeString      RequiredCode identifying the type of the event.
It should match the code property of one of your active billable metrics, otherwise it will be ignored
timestampInteger      Optional
Default: event reception timestamp
Unix timestamp in seconds of the event occurence (UTC).
If not provided, the API will set the event reception time
propertiesJSON      VariableExtra data to use for the event aggregation.
When mandatory, it should contains the field_name configured at billable metric level as key and any value as field value.
Aggregation type:
- COUNT: not used
- MAX: required. value must be a number
- SUM: required. value must be a number
- COUNT UNIQUE: required. value could have any datatype


The event has been stored in the system and will be aggregated to generate fees.

Returns an empty response body.