subscriptions

Update a subscription alert

Changed on Nov 5, 2026

This endpoint allows you to update an existing alert for a subscription. A non-empty thresholds array replaces the whole set of thresholds on the alert. When thresholds is left out, or sent as an empty array, the thresholds already on the alert are kept. A threshold sent with a code it already had, and without notify_on, keeps the notify_on it had.

put/subscriptions/{external_id}/alerts/{code}

Request

Base URL
https://api.getlago.com/api/v1
Auth
HTTP bearer
TypeScript
https://skmtc.dev/getlago/apis/lago-api-documentation/docs/subscriptions/:external_id/alerts/:code/put.ts
A function with typed inputs. Its response is checked against the schema.

Query parameters

subscription_status'pending' | 'active' | 'terminated' | 'canceled' | 'incomplete'

Example:active

Filter by subscription status. When provided, the subscription is looked up with this status instead of the default active status. Possible values are pending, active, terminated, canceled, or incomplete.

Request body

Example request

{
  "alert": {
    "code": "storage_threshold_alert",
    "name": "Storage Usage Alert",
    "thresholds": [
      {
        "code": "warn",
        "notify_on": [
          "triggered",
          "resolved"
        ]
      }
    ],
    "billable_metric_code": "storage_usage"
  }
}

Response

Subscription alert updated

Example response

{
  "alert": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "lago_organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "external_subscription_id": "sub_1234567890",
    "billable_metric": {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "name": "Storage",
      "code": "storage",
      "description": "GB of storage used in my application",
      "rounding_function": "round",
      "rounding_precision": 2,
      "created_at": "2022-09-14T16:35:31Z",
      "expression": "round((event.properties.ended_at - event.properties.started_at) * event.properties.units)",
      "field_name": "gb",
      "aggregation_type": "sum_agg",
      "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",
    "direction": "increasing",
    "previous_value": "1000.0",
    "last_processed_at": "2025-05-19T10:04:21Z",
    "thresholds": [
      {
        "code": "warn",
        "notify_on": [
          "triggered",
          "resolved"
        ],
        "value": "99.0"
      }
    ],
    "created_at": "2025-03-20T10:00:00Z"
  }
}

Changes

Nov 5, 2026b216574b9612 Revision changes
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property ////// became required for the status
Nov 3, 20265d26657495a3 Revision changes
- breaking
  request property //////// list-of-types was narrowed by removing types integer from media type application/json
- breaking
  added subschema #2 to the / response property oneOf list for the response status
- breaking
  the / response's property type changed from object to no type for status
- breaking
  the / response's property type changed from number to string for status
- breaking
  removed the required property // from the response with the status
- breaking
  removed the required property // from the response with the status
- breaking
  removed the required property // from the response with the status
- breaking
  removed the required property // from the response with the status
- breaking
  removed the required property // from the response with the status
- breaking
  removed the required property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  added the new billable_metric_lifetime_usage_units enum value to the / response property for the response status
- info
  added the new optional request property ///////////
- info
  added the new enum value incomplete to the query request parameter subscription_status
- info
  the ///////// request property type was generalized from integer to number
- info
  added the optional property /////// to the response with the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the //// response's property pattern was changed from ^[0-9]+.?[0-9]*$ to ^-?[0-9]+(\.[0-9]+)?$ for the status

Operation history