# Create an alert

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


[Idempotency Supported](/docs/api/idempotency)

Creates a new alert configuration. Depending on `type`, the alert can monitor usage, spend, or credit balance, and it can be [global or subscription-scoped](/docs/api/alerts/alert-object#global-vs-subscription-alerts) depending on whether `subscription_id` is provided.

**Note:** Creating an alert defines the threshold rule only. After an alert is created, Chargebee begins evaluating it as relevant billing data changes are processed. Alert statuses are created and updated during alert evaluation. The runtime evaluation state for each subscription is available via the [Alert Status](/docs/api/alert_statuses) endpoints.

### Prerequisites & Constraints

-   For `usage_exceeded` alerts, `metered_feature_id` must reference an existing metered feature configured on your site.
-   For `spend_exceeded` alerts, provide `currency_code`.
-   For `credit_balance_dropped` alerts, provide `unit_id` to identify the credit unit the alert applies to.
-   Provide only the input that matches the alert `type`: `metered_feature_id`, `currency_code`, and `unit_id` are mutually exclusive.
-   For `spend_exceeded` alerts, `threshold` `mode` is optional and defaults to `absolute` when omitted; if provided, it must be `absolute`. For `credit_balance_dropped` alerts, `threshold` `mode` must be `absolute`. Only `usage_exceeded` alerts support `percentage` mode.
-   For `filter_conditions`, only `plan_price_id` is supported as the `field`, with operator `equals` or `not_equals`.

### Use Cases

Create a usage alert

Set `type` to `usage_exceeded` and provide `metered_feature_id`. Use a `percentage` threshold to fire relative to the plan or feature quota (for example, at 90%), or an `absolute` threshold to fire at a specific usage quantity.

Create a spend alert

Set `type` to `spend_exceeded` and provide `currency_code`. The alert monitors the usage-based spend accumulated from metered addons (counting only usage beyond the included entitlement) and fires when it reaches the `absolute` threshold amount in that currency.

Create a credit balance alert

Set `type` to `credit_balance_dropped` and provide `unit_id`. The alert fires when the [credit balance](/docs/api/ledger_account_balances) for that unit drops to or below the `absolute` threshold.

## Sample Request

### Default

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}:\
     -d type="USAGE_EXCEEDED" \
     -d name="GPT-4o usage threshold" \
     -d description="Notify when usage crosses 90% of quota" \
     -d metered_feature_id="gpt4o-usage" \
     -d "threshold[mode]"="PERCENTAGE" \
     -d "threshold[value]"=90 \
     -d "filter_conditions[field][0]"="PLAN_PRICE_ID" \
     -d "filter_conditions[operator][0]"="EQUALS" \
     -d "filter_conditions[value][0]"="enterprise"
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;
using ChargeBee.Models.Enums;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Alert.Create()
		.Type(TypeEnum.UsageExceeded)
		.Name("GPT-4o usage threshold")
		.Description("Notify when usage crosses 90% of quota")
		.MeteredFeatureId("gpt4o-usage")
		.ThresholdMode(ModeEnum.Percentage)
		.ThresholdValue(90)
		.FilterConditionField(0, FilterCondition.FieldEnum.PlanPriceId)
		.FilterConditionOperator(0, FilterCondition.OperatorEnum.Equals)
		.FilterConditionValue(0, "enterprise")
		.Request();

Alert alert = result.Alert;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    alertAction "github.com/chargebee/chargebee-go/v3/actions/alert"
    "github.com/chargebee/chargebee-go/v3/models/alert"
    alertEnum "github.com/chargebee/chargebee-go/v3/models/alert/enum"
    enum "github.com/chargebee/chargebee-go/v3/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := alertAction.Create(&alert.CreateRequestParams{
        FilterConditions : []*alert.CreateFilterConditionParams{
            {
                Field : alertEnum.FilterConditionFieldPlanPriceId,
                Operator : alertEnum.FilterConditionOperatorEquals,
                Value : "enterprise",
            },
        },
        Type : enum.TypeUsageExceeded,
        Name : "GPT-4o usage threshold",
        Description : "Notify when usage crosses 90% of quota",
        MeteredFeatureId : "gpt4o-usage",
        Threshold : &alert.CreateThresholdParams{
            Mode : enum.ModePercentage,
            Value : chargebee.Float64(90),
        },
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        Alert := res.Alert
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.AlertCreateRequest{
    FilterConditions : []*chargebee.AlertCreateFilterCondition{
        {
            Field : chargebee.FilterConditionFieldPlanPriceId,
            Operator : chargebee.FilterConditionOperatorEquals,
            Value : "enterprise",
        },
    },
    Type : chargebee.TypeUsageExceeded,
    Name : "GPT-4o usage threshold",
    Description : "Notify when usage crosses 90% of quota",
    MeteredFeatureId : "gpt4o-usage",
    Threshold : &chargebee.AlertCreateThreshold{
        Mode : chargebee.ModePercentage,
        Value : chargebee.Float64(90),
    },
}
  res, err := client.Alert.Create(req)
      if err != nil {
        fmt.Println(err)
    } else {
        Alert := res.Alert
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = Alert.create()
            .type(Type.USAGE_EXCEEDED)
            .name("GPT-4o usage threshold")
            .description("Notify when usage crosses 90% of quota")
            .meteredFeatureId("gpt4o-usage")
            .thresholdMode(Mode.PERCENTAGE)
            .thresholdValue(90.0)
            .filterConditionField(0, Alert.FilterCondition.Field.PLAN_PRICE_ID)
            .filterConditionOperator(0, Alert.FilterCondition.Operator.EQUALS)
            .filterConditionValue(0, "enterprise")
            .request();

        Alert alert = result.alert();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.alert.Alert;
import com.chargebee.v4.models.alert.params.AlertCreateParams;
import com.chargebee.v4.models.alert.responses.AlertCreateResponse;
import java.util.List;

public class AlertCreate {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        AlertCreateParams.ThresholdParams thresholdParams =
            AlertCreateParams.ThresholdParams.builder()
                .mode(AlertCreateParams.ThresholdParams.Mode.PERCENTAGE)
                .value(90.0)
                .build();

        AlertCreateParams.FilterConditionsParams filterCondition0 =
            AlertCreateParams.FilterConditionsParams.builder()
                .field(AlertCreateParams.FilterConditionsParams.Field.PLAN_PRICE_ID)
                .operator(AlertCreateParams.FilterConditionsParams.Operator.EQUALS)
                .value("enterprise")
                .build();

        List<AlertCreateParams.FilterConditionsParams> filterConditionsList =
            List.of(filterCondition0);

        AlertCreateParams params = AlertCreateParams.builder()
            .type(AlertCreateParams.Type.USAGE_EXCEEDED)
            .name("GPT-4o usage threshold")
            .description("Notify when usage crosses 90% of quota")
            .meteredFeatureId("gpt4o-usage")
            .threshold(thresholdParams)
            .filterConditions(filterConditionsList)
            .build();

        AlertCreateResponse response = client.alerts().create(params);

        Alert alert = response.getAlert();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.alert.create({
        filter_conditions: [
            {
                field: "plan_price_id",
                operator: "equals",
                value: "enterprise"
            }
        ],
        type: "usage_exceeded",
        name: "GPT-4o usage threshold",
        description: "Notify when usage crosses 90% of quota",
        metered_feature_id: "gpt4o-usage",
        threshold: {
            mode: "percentage",
            value: 90
        }
    });

    console.log(result);
    const alert = result.alert;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->alert()->create([
    "filter_conditions" => [
        [
            "field" => "plan_price_id",
            "operator" => "equals",
            "value" => "enterprise"
        ]
    ],
    "type" => "usage_exceeded",
    "name" => "GPT-4o usage threshold",
    "description" => "Notify when usage crosses 90% of quota",
    "metered_feature_id" => "gpt4o-usage",
    "threshold" => [
        "mode" => "percentage",
        "value" => 90
    ]
]);
$alert = $result->alert;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.Alert.create(
    cb_client.Alert.CreateParams(
        filter_conditions=[
            cb_client.Alert.CreateFilterConditionParams(
              field=chargebee.Alert.FilterConditionField.PLAN_PRICE_ID,
              operator=chargebee.Alert.FilterConditionOperator.EQUALS,
              value="enterprise"
            )
        ],
        type=chargebee.Type.USAGE_EXCEEDED,
        name="GPT-4o usage threshold",
        description="Notify when usage crosses 90% of quota",
        metered_feature_id="gpt4o-usage",
        threshold=cb_client.Alert.CreateThresholdParams(
            mode=chargebee.Mode.PERCENTAGE,
            value=90
        )
    )
)
alert = response.alert
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::Alert.create({
  :type => "USAGE_EXCEEDED",
  :name => "GPT-4o usage threshold",
  :description => "Notify when usage crosses 90% of quota",
  :metered_feature_id => "gpt4o-usage",
  :threshold => {
    :mode => "PERCENTAGE",
    :value => 90
  },
  :filter_conditions => [
    {
      :field => "PLAN_PRICE_ID",
      :operator => "EQUALS",
      :value => "enterprise"
    }
  ]
})

alert = result.alert
```

### Create a credit balance alert

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}:\
     -d type="CREDIT_BALANCE_DROPPED" \
     -d name="Low AI credits" \
     -d description="Warn when remaining AI credits drop to or below 10" \
     -d unit_id="ai_credits" \
     -d "threshold[mode]"="ABSOLUTE" \
     -d "threshold[value]"=10
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;
using ChargeBee.Models.Enums;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Alert.Create()
		.Type(TypeEnum.CreditBalanceDropped)
		.Name("Low AI credits")
		.Description("Warn when remaining AI credits drop to or below 10")
		.UnitId("ai_credits")
		.ThresholdMode(ModeEnum.Absolute)
		.ThresholdValue(10)
		.Request();

Alert alert = result.Alert;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    alertAction "github.com/chargebee/chargebee-go/v3/actions/alert"
    "github.com/chargebee/chargebee-go/v3/models/alert"
    enum "github.com/chargebee/chargebee-go/v3/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := alertAction.Create(&alert.CreateRequestParams{
        Type : enum.TypeCreditBalanceDropped,
        Name : "Low AI credits",
        Description : "Warn when remaining AI credits drop to or below 10",
        UnitId : "ai_credits",
        Threshold : &alert.CreateThresholdParams{
            Mode : enum.ModeAbsolute,
            Value : chargebee.Float64(10),
        },
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        Alert := res.Alert
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.AlertCreateRequest{
    Type : chargebee.TypeCreditBalanceDropped,
    Name : "Low AI credits",
    Description : "Warn when remaining AI credits drop to or below 10",
    UnitId : "ai_credits",
    Threshold : &chargebee.AlertCreateThreshold{
        Mode : chargebee.ModeAbsolute,
        Value : chargebee.Float64(10),
    },
}
  res, err := client.Alert.Create(req)
      if err != nil {
        fmt.Println(err)
    } else {
        Alert := res.Alert
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = Alert.create()
            .type(Type.CREDIT_BALANCE_DROPPED)
            .name("Low AI credits")
            .description("Warn when remaining AI credits drop to or below 10")
            .unitId("ai_credits")
            .thresholdMode(Mode.ABSOLUTE)
            .thresholdValue(10.0)
            .request();

        Alert alert = result.alert();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.alert.Alert;
import com.chargebee.v4.models.alert.params.AlertCreateParams;
import com.chargebee.v4.models.alert.responses.AlertCreateResponse;

public class AlertCreate {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        AlertCreateParams.ThresholdParams thresholdParams =
            AlertCreateParams.ThresholdParams.builder()
                .mode(AlertCreateParams.ThresholdParams.Mode.ABSOLUTE)
                .value(10.0)
                .build();

        AlertCreateParams params = AlertCreateParams.builder()
            .type(AlertCreateParams.Type.CREDIT_BALANCE_DROPPED)
            .name("Low AI credits")
            .description("Warn when remaining AI credits drop to or below 10")
            .unitId("ai_credits")
            .threshold(thresholdParams)
            .build();

        AlertCreateResponse response = client.alerts().create(params);

        Alert alert = response.getAlert();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.alert.create({
        type: "credit_balance_dropped",
        name: "Low AI credits",
        description: "Warn when remaining AI credits drop to or below 10",
        unit_id: "ai_credits",
        threshold: {
            mode: "absolute",
            value: 10
        }
    });

    console.log(result);
    const alert = result.alert;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->alert()->create([
    "type" => "credit_balance_dropped",
    "name" => "Low AI credits",
    "description" => "Warn when remaining AI credits drop to or below 10",
    "unit_id" => "ai_credits",
    "threshold" => [
        "mode" => "absolute",
        "value" => 10
    ]
]);
$alert = $result->alert;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.Alert.create(
    cb_client.Alert.CreateParams(
        type=chargebee.Type.CREDIT_BALANCE_DROPPED,
        name="Low AI credits",
        description="Warn when remaining AI credits drop to or below 10",
        unit_id="ai_credits",
        threshold=cb_client.Alert.CreateThresholdParams(
            mode=chargebee.Mode.ABSOLUTE,
            value=10
        )
    )
)
alert = response.alert
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::Alert.create({
  :type => "CREDIT_BALANCE_DROPPED",
  :name => "Low AI credits",
  :description => "Warn when remaining AI credits drop to or below 10",
  :unit_id => "ai_credits",
  :threshold => {
    :mode => "ABSOLUTE",
    :value => 10
  }
})

alert = result.alert
```

### Create a spend alert

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}:\
     -d type="SPEND_EXCEEDED" \
     -d name="Monthly overage spend" \
     -d description="Alert when metered-addon overage spend crosses 500 USD" \
     -d currency_code="USD" \
     -d "threshold[mode]"="ABSOLUTE" \
     -d "threshold[value]"=500
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;
using ChargeBee.Models.Enums;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Alert.Create()
		.Type(TypeEnum.SpendExceeded)
		.Name("Monthly overage spend")
		.Description("Alert when metered-addon overage spend crosses 500 USD")
		.CurrencyCode("USD")
		.ThresholdMode(ModeEnum.Absolute)
		.ThresholdValue(500)
		.Request();

Alert alert = result.Alert;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    alertAction "github.com/chargebee/chargebee-go/v3/actions/alert"
    "github.com/chargebee/chargebee-go/v3/models/alert"
    enum "github.com/chargebee/chargebee-go/v3/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := alertAction.Create(&alert.CreateRequestParams{
        Type : enum.TypeSpendExceeded,
        Name : "Monthly overage spend",
        Description : "Alert when metered-addon overage spend crosses 500 USD",
        CurrencyCode : "USD",
        Threshold : &alert.CreateThresholdParams{
            Mode : enum.ModeAbsolute,
            Value : chargebee.Float64(500),
        },
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        Alert := res.Alert
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.AlertCreateRequest{
    Type : chargebee.TypeSpendExceeded,
    Name : "Monthly overage spend",
    Description : "Alert when metered-addon overage spend crosses 500 USD",
    CurrencyCode : "USD",
    Threshold : &chargebee.AlertCreateThreshold{
        Mode : chargebee.ModeAbsolute,
        Value : chargebee.Float64(500),
    },
}
  res, err := client.Alert.Create(req)
      if err != nil {
        fmt.Println(err)
    } else {
        Alert := res.Alert
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = Alert.create()
            .type(Type.SPEND_EXCEEDED)
            .name("Monthly overage spend")
            .description("Alert when metered-addon overage spend crosses 500 USD")
            .currencyCode("USD")
            .thresholdMode(Mode.ABSOLUTE)
            .thresholdValue(500.0)
            .request();

        Alert alert = result.alert();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.alert.Alert;
import com.chargebee.v4.models.alert.params.AlertCreateParams;
import com.chargebee.v4.models.alert.responses.AlertCreateResponse;

public class AlertCreate {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        AlertCreateParams.ThresholdParams thresholdParams =
            AlertCreateParams.ThresholdParams.builder()
                .mode(AlertCreateParams.ThresholdParams.Mode.ABSOLUTE)
                .value(500.0)
                .build();

        AlertCreateParams params = AlertCreateParams.builder()
            .type(AlertCreateParams.Type.SPEND_EXCEEDED)
            .name("Monthly overage spend")
            .description("Alert when metered-addon overage spend crosses 500 USD")
            .currencyCode("USD")
            .threshold(thresholdParams)
            .build();

        AlertCreateResponse response = client.alerts().create(params);

        Alert alert = response.getAlert();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.alert.create({
        type: "spend_exceeded",
        name: "Monthly overage spend",
        description: "Alert when metered-addon overage spend crosses 500 USD",
        currency_code: "USD",
        threshold: {
            mode: "absolute",
            value: 500
        }
    });

    console.log(result);
    const alert = result.alert;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->alert()->create([
    "type" => "spend_exceeded",
    "name" => "Monthly overage spend",
    "description" => "Alert when metered-addon overage spend crosses 500 USD",
    "currency_code" => "USD",
    "threshold" => [
        "mode" => "absolute",
        "value" => 500
    ]
]);
$alert = $result->alert;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.Alert.create(
    cb_client.Alert.CreateParams(
        type=chargebee.Type.SPEND_EXCEEDED,
        name="Monthly overage spend",
        description="Alert when metered-addon overage spend crosses 500 USD",
        currency_code="USD",
        threshold=cb_client.Alert.CreateThresholdParams(
            mode=chargebee.Mode.ABSOLUTE,
            value=500
        )
    )
)
alert = response.alert
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::Alert.create({
  :type => "SPEND_EXCEEDED",
  :name => "Monthly overage spend",
  :description => "Alert when metered-addon overage spend crosses 500 USD",
  :currency_code => "USD",
  :threshold => {
    :mode => "ABSOLUTE",
    :value => 500
  }
})

alert = result.alert
```

## Sample Response

```json
{
  "alert": {
    "id": "alert___dev__3Nl7purV3LwbKYH",
    "name": "GPT-4o usage threshold",
    "description": "Notify when usage crosses 90% of quota",
    "type": "usage_exceeded",
    "metered_feature_id": "gpt4o-usage",
    "threshold": {
      "mode": "percentage",
      "value": 90
    },
    "filter_conditions": [
      {
        "field": "plan_price_id",
        "operator": "equals",
        "value": "enterprise"
      },
      {..}
    ],
    "subscription_id": null,
    "status": "enabled",
    "object": "alert",
    "resource_version": 1763879971000,
    "created_at": 1763879971,
    "updated_at": 1763879971
  }
}
```

## URL Format

**POST** https://[site].chargebee.com/api/v2/alerts

## Input Parameters

- `type` (required, enumerated string)
  The type of alert to create. Determines what the alert measures, which input it requires, and how the `threshold` is interpreted.
  Possible enum values:
    - `usage_exceeded`
      The alert fires when usage of the [metered feature](/docs/api/usages) (identified by `metered_feature_id`) reaches or exceeds the configured threshold. Supports both `percentage` and `absolute` threshold modes.
    - `spend_exceeded`
      The alert fires when the total usage-based spend accumulated from metered addons reaches or exceeds the configured threshold. Only spend from usage beyond the included entitlement is counted. See [usage charges](/docs/api/usage_charges) for how overage spend is computed. The `threshold` mode is always `absolute`.
    - `credit_balance_dropped`
      The alert fires when the [credit balance](/docs/api/ledger_account_balances) for the configured credit unit drops to or below the configured threshold. The `threshold` mode is always `absolute`.

- `name` (required, string, max chars=50)
  A human-readable name for the alert. Maximum 50 characters.

- `description` (optional, string, max chars=65k)
  An optional description providing additional context about the alert. Maximum 65,000 characters.

- `metered_feature_id` (optional, string, max chars=50)
  Identifier of the [metered feature](/docs/api/usages) that the alert should monitor. Required when `type` is `usage_exceeded`; do not set it for other alert types.

- `currency_code` (optional, string, max chars=3)
  The ISO [currency code](/docs/api/currencies/currency-object#currency_code) in which the metered-addon overage spend is measured. Required when `type` is `spend_exceeded`; do not set it for other alert types.

- `unit_id` (optional, string, max chars=50)
  Identifier of the credit unit that the alert should monitor. Required when `type` is `credit_balance_dropped`; do not set it for other alert types.

- `subscription_id` (optional, string, max chars=50)
  The identifier of the [subscription](/docs/api/subscriptions) to scope this alert to. If omitted, the alert is created as a global alert. If provided, `filter_conditions` must not be set.

- `meta` (optional, string, max chars=65k)
  An optional string field for storing custom metadata with the alert (for example, JSON serialized by your integration). Maximum 65,000 characters.

- `threshold` (optional, enumerated string)
  The threshold configuration that defines when this alert fires.
  - `mode` (optional, enumerated string)
    How the threshold `value` is interpreted. `usage_exceeded` alerts support `percentage` or `absolute`. For `spend_exceeded` alerts, `mode` is optional and defaults to `absolute` when omitted; if provided, it must be `absolute`. For `credit_balance_dropped` alerts, `mode` must be `absolute`.
    Possible enum values:
      - `absolute`
        The threshold `value` represents an absolute quantity: a usage quantity for `usage_exceeded`, an overage spend amount for `spend_exceeded`, or a credit-balance floor for `credit_balance_dropped`. For `spend_exceeded`, the amount is expressed in the major units of `currency_code` (for example, dollars—not cents—for `USD`, so `500.0` means 500 USD).
      - `percentage`
        The threshold `value` represents a percentage (0-100) of the plan or feature quota. Supported only for `usage_exceeded` alerts.
  - `value` (required, double)
    The numeric threshold at which the alert fires. For `percentage` mode, this must be between 0 and 100 inclusive. For `absolute` mode, this must be >= 0.

- `filter_conditions` (optional, array)
  An array of conditions that restrict which subscriptions a global alert applies to. Multiple conditions are evaluated with OR logic. Cannot be set when `subscription_id` is provided.
  - `field` (optional, enumerated string)
    The subscription attribute to filter on. Currently only `plan_price_id` is supported.
    Possible enum values:
      - `plan_price_id`
        Filters by the plan price associated with the subscription.
  - `operator` (optional, enumerated string)
    The comparison operator for the filter condition.
    Possible enum values:
      - `equals`
        The subscription attribute must equal the specified `value`.
      - `not_equals`
        The subscription attribute must not equal the specified `value`.
  - `value` (optional, string, max chars=50)
    The value to compare against, for example, a specific plan price identifier. Maximum 50 characters.

## Returns

- `alert` (Alert object)
  Resource object representing alert.