LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
curl --location --request POST "$LAGO_URL/api/v1/events/batch" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"events": [
{
"transaction_id": "__UNIQUE_ID__",
"external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
"code": "__BILLABLE_METRIC_CODE__",
"timestamp": $(date +%s),
"properties": {
"custom_field": 12
}
}
]
}'
{
"events": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"transaction_id": "transaction_1234567890",
"lago_customer_id": null,
"code": "storage",
"timestamp": "2022-04-29T08:59:51.123Z",
"lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"external_subscription_id": "sub_1234567890",
"created_at": "2022-04-29T08:59:51Z",
"precise_total_amount_cents": "1234.56",
"properties": {
"gb": 10
}
}
]
}Batch usage events
This endpoint can be used to send a batch of usage records. Each request may include up to 100 events.
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
curl --location --request POST "$LAGO_URL/api/v1/events/batch" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"events": [
{
"transaction_id": "__UNIQUE_ID__",
"external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
"code": "__BILLABLE_METRIC_CODE__",
"timestamp": $(date +%s),
"properties": {
"custom_field": 12
}
}
]
}'
{
"events": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"transaction_id": "transaction_1234567890",
"lago_customer_id": null,
"code": "storage",
"timestamp": "2022-04-29T08:59:51.123Z",
"lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"external_subscription_id": "sub_1234567890",
"created_at": "2022-04-29T08:59:51Z",
"precise_total_amount_cents": "1234.56",
"properties": {
"gb": 10
}
}
]
}LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
curl --location --request POST "$LAGO_URL/api/v1/events/batch" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"events": [
{
"transaction_id": "__UNIQUE_ID__",
"external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
"code": "__BILLABLE_METRIC_CODE__",
"timestamp": $(date +%s),
"properties": {
"custom_field": 12
}
}
]
}'
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Batch events payload
Show child attributes
Show child attributes
This field represents a unique identifier for the event. It is crucial for ensuring idempotency, meaning that each event can be uniquely identified and processed without causing any unintended side effects.
WARNING: If the Lago 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 a new event arrives with identical values for these two fields as an existing event, the new one will overwrite the previous event rather than being rejected.
"transaction_1234567890"
The unique identifier of the subscription in your application. This field is mandatory in order to link events to the correct customer subscription.
"sub_1234567890"
The code that identifies a targeted billable metric. It is essential that this code matches the code property of one of your active billable metrics. If the provided code does not correspond to any active billable metric, it will be ignored during the process.
"storage"
This field captures the Unix timestamp in seconds indicating the occurrence of the event in Coordinated Universal Time (UTC). If this timestamp is not provided, the API will automatically set it to the time of event reception. You can also provide miliseconds precision by appending decimals to the timestamp.
"1651240791.123"
The precise total amount in cents with precision used by the dynamic pricing model to compute the usage amount.
"1234.56"
This field represents additional properties associated with the event, which are utilized in the calculation of the final fee. This object becomes mandatory when the targeted billable metric employs a sum_agg, max_agg, or unique_count_agg aggregation method. However, when using a simple count_agg, this object is not required.
Show child attributes
Show child attributes
{ "gb": 10 }Response
Event received
Show child attributes
Show child attributes
Unique identifier assigned to the event within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the event's record within the Lago system
"1a901a90-1a90-1a90-1a90-1a901a901a90"
This field represents a unique identifier for the event. It is crucial for ensuring idempotency, meaning that each event can be uniquely identified and processed without causing any unintended side effects.
"transaction_1234567890"
Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system The value will always be null in this response as the event processing is done asynchronously
null
The code that identifies a targeted billable metric. It is essential that this code matches the code property of one of your active billable metrics. If the provided code does not correspond to any active billable metric, it will be ignored during the process.
"storage"
This field captures the Unix timestamp in seconds indicating the occurrence of the event in Coordinated Universal Time (UTC). If this timestamp is not provided, the API will automatically set it to the time of event reception.
"2022-04-29T08:59:51.123Z"
Unique identifier assigned to the subscription within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the subscription's record within the Lago system
"1a901a90-1a90-1a90-1a90-1a901a901a90"
The unique identifier of the subscription within your application. It is a mandatory field when the customer possesses multiple subscriptions or when the external_customer_id is not provided.
"sub_1234567890"
The creation date of the event's record in the Lago application, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Lago application
"2022-04-29T08:59:51Z"
The precise total amount that was sent in the event payload. This filed is used by the dynamic pricing model.
"1234.56"
This field represents additional properties associated with the event, which are utilized in the calculation of the final fee. This object becomes mandatory when the targeted billable metric employs a sum_agg, max_agg, or unique_count_agg aggregation method. However, when using a simple count_agg, this object is not required.
Show child attributes
Show child attributes
The operation_type field is only necessary when adding or removing a specific unit when the targeted billable metric adopts a unique_count_agg aggregation method. In other cases, the operation_type field is not required. The valid values for the operation_type field are add or remove, which indicate whether the unit is being added or removed from the unique count aggregation, respectively.
add, remove { "gb": 10 }