Skip to main content

Batch Events

Batch events represents the data delivered to lago application that will then be aggregated into billable metrics. The following endpoint explains how to send events for multiple subscriptions for one customer.





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


"event": {
"transaction_id": "__UNIQUE_ID__",
"external_customer_id": "__YOUR_CUSTOMER_ID__",
"external_subscription_ids": ["id1", "id2"],
"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_idsArray      RequiredArray of subscription IDs associated with the customer
external_customer_idString      OptionalCustomer unique identifier in your application
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 of the event occurence in 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: optional
- MAX: required. value must be an integer
- SUM: required. value must be an integer
- COUNT UNIQUE: required. value could have any datatype
- RECURRING COUNT: required. value must be the unique identifier of the persisted object.

Recurring count aggregation

Content of the event properties field:

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.