subscriptions

Create subscription alert(s)

Changed on Nov 5, 2026

This endpoint allows you to create alerts for a subscription. Send a single alert object wrapped in alert key to create one alert, or an array of alert objects wrapped in alerts key to create multiple alerts atomically.

post/subscriptions/{external_id}/alerts

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/post.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"
        ]
      }
    ],
    "alert_type": "billable_metric_current_usage_amount",
    "billable_metric_code": "storage_usage"
  }
}

Response

Subscription alert(s) created

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
- 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
  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
  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
  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
- 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
  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
- 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 optional request property ///////////////
- info
  added the new enum value incomplete to the query request parameter subscription_status
- info
  added the new billable_metric_lifetime_usage_units enum value to the request property ///////
- info
  added the new billable_metric_lifetime_usage_units enum value to the request property //////
- info
  the ////////////// request property type was generalized from integer to number
- info
  the ///////////// request property type was generalized from integer to number
- info
  added the optional property /////////// to the response with the status
- 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 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
- info
  the ///////// response's property pattern was changed from ^[0-9]+.?[0-9]*$ to ^-?[0-9]+(\.[0-9]+)?$ for the status

Operation history