curl --request PUT \
--url https://api.getlago.com/api/v1/subscriptions/{external_id}/alerts/{code} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"alert": {
"code": "storage_threshold_alert",
"billable_metric_code": "storage_usage",
"name": "Storage Usage Alert",
"thresholds": [
{
"value": 99,
"code": "warn",
"recurring": false
}
]
}
}
'{
"alert": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"lago_organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"subscription_external_id": "sub_1234567890",
"customer_external_id": "cus_0987654321",
"billable_metric": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "Storage",
"code": "storage",
"recurring": false,
"created_at": "2022-09-14T16:35:31Z",
"aggregation_type": "sum_agg",
"description": "GB of storage used in my application",
"rounding_function": "round",
"rounding_precision": 2,
"expression": "round((ended_at - started_at) * units)",
"field_name": "gb",
"weighted_interval": "seconds",
"filters": [
{
"key": "region",
"values": [
"us-east-1"
]
}
]
},
"alert_type": "billable_metric_current_usage_amount",
"code": "storage_threshold_alert",
"name": "Storage Usage Alert",
"previous_value": 1000,
"last_processed_at": "2025-05-19T10:04:21Z",
"thresholds": [
{
"code": "warn",
"recurring": false,
"value": "99.0"
}
],
"created_at": "2025-03-20T10:00:00Z"
}
}Update an alert
This endpoint allows you to update an existing alert for a subscription.
curl --request PUT \
--url https://api.getlago.com/api/v1/subscriptions/{external_id}/alerts/{code} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"alert": {
"code": "storage_threshold_alert",
"billable_metric_code": "storage_usage",
"name": "Storage Usage Alert",
"thresholds": [
{
"value": 99,
"code": "warn",
"recurring": false
}
]
}
}
'{
"alert": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"lago_organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"subscription_external_id": "sub_1234567890",
"customer_external_id": "cus_0987654321",
"billable_metric": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "Storage",
"code": "storage",
"recurring": false,
"created_at": "2022-09-14T16:35:31Z",
"aggregation_type": "sum_agg",
"description": "GB of storage used in my application",
"rounding_function": "round",
"rounding_precision": 2,
"expression": "round((ended_at - started_at) * units)",
"field_name": "gb",
"weighted_interval": "seconds",
"filters": [
{
"key": "region",
"values": [
"us-east-1"
]
}
]
},
"alert_type": "billable_metric_current_usage_amount",
"code": "storage_threshold_alert",
"name": "Storage Usage Alert",
"previous_value": 1000,
"last_processed_at": "2025-05-19T10:04:21Z",
"thresholds": [
{
"code": "warn",
"recurring": false,
"value": "99.0"
}
],
"created_at": "2025-03-20T10:00:00Z"
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
External ID of the existing subscription
"5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"
Unique code of the alert
"storage_threshold_alert"
Body
Update an existing alert for a subscription
Show child attributes
Show child attributes
Unique code used to identify the alert.
"storage_threshold_alert"
The code of the billable metric associated with the alert. Only for alerts based on a billable metric.
"storage_usage"
The name of the alert.
"Storage Usage Alert"
Array of thresholds associated with the alert.
Show child attributes
Show child attributes
A value that should trigger this alert. This can be an integer or a string formatted as a BigDecimal.
99
Unique identifier of the usage threshold created by Lago.
"warn"
This field when set to true indicates that the alert will be retrigger when this threshold is reached after the last non-recurring threshold. Only one recurring threshold per alert allowed.
false
Response
Subscription alert updated
Show child attributes
Show child attributes
Unique identifier of the alert, created by Lago.
"1a901a90-1a90-1a90-1a90-1a901a901a90"
Unique identifier of the organization, created by Lago.
"1a901a90-1a90-1a90-1a90-1a901a901a90"
The subscription external unique identifier (provided by your own application).
"sub_1234567890"
The customer external unique identifier (provided by your own application).
"cus_0987654321"
The billable metric associated with the alert. Only for alerts based on a billable metric.
Show child attributes
Show child attributes
Unique identifier of the billable metric created by Lago.
"1a901a90-1a90-1a90-1a90-1a901a901a90"
Name of the billable metric.
"Storage"
Unique code used to identify the billable metric associated with the API request. This code associates each event with the correct metric.
"storage"
Defines if the billable metric is persisted billing period over billing period.
- If set to
true: the accumulated number of units calculated from the previous billing period is persisted to the next billing period. - If set to
false: the accumulated number of units is reset to 0 at the end of the billing period. - If not defined in the request, default value is
false.
false
Creation date of the billable metric.
"2022-09-14T16:35:31Z"
Aggregation method used to compute usage for this billable metric.
count_agg, sum_agg, max_agg, unique_count_agg, weighted_sum_agg, latest_agg "sum_agg"
Internal description of the billable metric.
"GB of storage used in my application"
Refers to the numeric value or mathematical expression that will be rounded based on the calculated number of billing units. Possible values are round, ceil and floor.
ceil, floor, round, "round"
Specifies the number of decimal places to which the rounding_function will be rounded. It can be a positive or negative value.
2
Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units.
"round((ended_at - started_at) * units)"
Property of the billable metric used for aggregating usage data. This field is not required for count_agg.
"gb"
Parameter exclusively utilized in conjunction with the weighted_sum aggregation type. It serves to adjust the aggregation result by assigning weights and proration to the result based on time intervals. When this field is not provided, the default time interval is assumed to be in seconds.
seconds, "seconds"
The type of alert.
current_usage_amount, billable_metric_current_usage_amount, billable_metric_current_usage_units, lifetime_usage_amount "billable_metric_current_usage_amount"
Unique code used to identify the alert.
"storage_threshold_alert"
The name of the alert.
"Storage Usage Alert"
When the system checked if this alert should be triggered, this value was retrieved and checked against the thresholds.
1000
The date and time in UTC (ISO 8601) when the system checked if this alert should be triggered. Null until it's processed for the first time.
"2025-05-19T10:04:21Z"
Array of thresholds associated with the alert.
Show child attributes
Show child attributes
Unique identifier of the usage threshold created by Lago.
"warn"
This field when set to true indicates that the alert will be retrigger when this threshold is reached after the last non-recurring threshold. Only one recurring threshold per alert allowed.
false
A value that should trigger this alert, formatted as a BigDecimal.
"99.0"
The date and time in UTC (ISO 8601) when the alert was created.
"2025-03-20T10:00:00Z"