GEgetlago
subscriptions

Create subscription alert(s)

Changed on

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

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

OR

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

OR

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

  • b216574b9612Revision 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

  • 5d26657495a3Revision changes
    • info

      added the new optional request property ////////////////

    • info

      added the new optional request property ///////////////

    • info

      added the optional property /////////// to the response with the status

    • info

      added the optional property //////////// to the response with the status