Skip to main content

Persisted events

Events represents the data delivered to lago application that will then be aggregated into billable metrics. By sending a persisted event, it's kept in memory and persisted through the next billable periods, unless you or your clients change it. At the end of each period, the total units to be charged is resumed to 0. Persisted events are available for all billable metrics having the following aggregation type: RECURRING_COUNT.

The following endpoint explains how to send a persisted event to a specific 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,
"operation_type": "add"


"event": {
"transaction_id": "__UNIQUE_ID__",
"external_customer_id": "__CUSTOMER_ID__",
"external_subscription_id": "__SUBSCRIPTION_ID__",
"code": "__EVENT_CODE__",
"timestamp": 1650893379,
"properties": {
"custom_field": 12,
"operation_type": "add"
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.
It might also contain an operation_type that can be either add or remove.
Aggregation type:
- RECURRING COUNT: required. value must be the unique identifier of the persisted object.

Content of the event properties object

field_name (*)String      Required(*) Key must be the field_name configured at billable metric level and be the unique identifier of the object to persist.
operation_typeString      RequiredType of operation to perform on the persisted object.
Possible values
- add: Add or unsuspend a persisted object.
- remove: Remove or suspend a persisted object.


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

Returns an empty response body.