---
title: "Create subscription alert"
method: POST
path: "/alerts/subscription_id/{subscription_id}"
tags: ["Alert"]
---

# Create subscription alert

`POST /alerts/subscription_id/{subscription_id}`

This endpoint is used to create alerts at the subscription level.

Subscription level alerts can be one of two types: `usage_exceeded` or `cost_exceeded`. A `usage_exceeded` alert is
scoped to a particular metric and is triggered when the usage of that metric exceeds predefined thresholds during the
current billing cycle. A `cost_exceeded` alert is triggered when the total amount due during the current billing cycle surpasses
predefined thresholds. `cost_exceeded` alerts do not include burndown of pre-purchase credits. Each subscription can have one
`cost_exceeded` alert and one `usage_exceeded` alert per metric that is a part of the subscription. Alerts are triggered based
on usage or cost conditions met during the current billing cycle.

## Path parameters

- `subscription_id` string, required

## Request body

- CreateSubscriptionAlertRequestParams
  - `thresholds` Threshold[], required — The thresholds that define the values at which the alert will be triggered.
    - `value` number, required — The value at which an alert will fire. For credit balance alerts, the alert will fire at or below this value. For usage and cost alerts, the alert will fire at or above this value.
  - `type` 'usage_exceeded' | 'cost_exceeded', required — The type of alert to create. This must be a valid alert type.
  - `metric_id` string, nullable — The metric to track usage for.
  - `grouping_keys` string[], nullable — The property keys to group cost alerts by. Only applicable for cost_exceeded alerts.
  - `currency` string, nullable — The case sensitive currency or custom pricing unit to use for grouped cost alerts. Required when grouping_keys is set.
  - `price_filters` PriceFilter[], nullable — Filters to scope which prices are included in grouped cost alert evaluation. Supports filtering by price_id, item_id, or price_type with includes/excludes operators. Only applicable when grouping_keys is set.
    - `field` 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id', required — The property of the price to filter on.
    - `operator` 'includes' | 'excludes', required — Should prices that match the filter be included or excluded.
    - `values` string[], required — The IDs or values that match this filter.
  - `threshold_overrides` ThresholdOverrideParams[], nullable — Per-group threshold overrides. Each override maps a specific combination of grouping_keys values to a list of thresholds that fully replaces the default thresholds for that group. An empty thresholds list silences the group. Groups without an override use the default thresholds. Only applicable when grouping_keys is set.
    - `group_values` string[], required — The values of the grouping keys that identify this group. The list length must match the alert's grouping_keys, and values appear in the same order as grouping_keys.
    - `thresholds` Threshold[], required — The thresholds to apply to this group. An empty list silences alerts for this group. A non-empty list fully replaces the default thresholds for this group.
      - `value` number, required — The value at which an alert will fire. For credit balance alerts, the alert will fire at or below this value. For usage and cost alerts, the alert will fire at or above this value.

## Response `201`

Created

- Alert — [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending, usage, or credit balance and trigger webhooks when a threshold is exceeded. Alerts created through the API can be scoped to either customers or subscriptions.
  - `id` string, required — Also referred to as alert_id in this documentation.
  - `type` union, required — The type of alert. This must be a valid alert type.
    - 'credit_balance_depleted' | 'credit_balance_dropped' | 'credit_balance_recovered'
    - 'usage_exceeded' | 'cost_exceeded'
    - 'license_balance_threshold_reached'
  - `created_at` string, date-time, required — The creation time of the resource in Orb.
  - `enabled` boolean, required — Whether the alert is enabled or disabled.
  - `thresholds` Threshold[], nullable, required — The thresholds that define the conditions under which the alert will be triggered.
    - `value` number, required — The value at which an alert will fire. For credit balance alerts, the alert will fire at or below this value. For usage and cost alerts, the alert will fire at or above this value.
  - `customer` CustomerMinified, required
    - `id` string, required
    - `external_customer_id` string, nullable, required
  - `plan` PlanMinifiedWithVersion, required
    - `id` string, nullable, required
    - `external_plan_id` string, nullable, required — An optional user-defined ID for this plan resource, used throughout the system as an alias for this Plan. Use this field to identify a plan by an existing identifier in your system.
    - `name` string, nullable, required
    - `plan_version` string, required
  - `subscription` SubscriptionMinified, required
    - `id` string, required
  - `metric` BillableMetricMinified, required
    - `id` string, required
  - `license_type` LicenseTypeMinified — Minified license type for alert serialization.
    - `id` string, required
  - `currency` string, nullable, required — The name of the currency the credit balance or invoice cost is denominated in.
  - `grouping_keys` string[], nullable — The property keys to group cost alerts by. Only present for cost alerts with grouping enabled.
  - `price_filters` PriceFilter[], nullable — Filters scoping which prices are included in grouped cost alert evaluation.
    - `field` 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id', required — The property of the price to filter on.
    - `operator` 'includes' | 'excludes', required — Should prices that match the filter be included or excluded.
    - `values` string[], required — The IDs or values that match this filter.
  - `threshold_overrides` ThresholdOverride[], nullable — Per-group threshold overrides. Each override maps a specific combination of grouping_keys values to a replacement threshold list. Only present for grouped cost alerts that have at least one override.
    - `group_values` string[], required — The values of the grouping keys that identify this group. The list length matches the alert's grouping_keys.
    - `thresholds` Threshold[], required — The thresholds applied to this group. An empty list means the group is silenced.
      - `value` number, required — The value at which an alert will fire. For credit balance alerts, the alert will fire at or below this value. For usage and cost alerts, the alert will fire at or above this value.
  - `balance_alert_status` BalanceAlertStatus[], nullable — The current status of the alert. This field is only present for credit balance alerts.
    - `threshold_value` number, required — The value of the threshold that defines the alert status.
    - `in_alert` boolean, required — Whether the alert is currently in-alert or not.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict
- `413` — Content Too Large
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.dev/withorb/apis/api-reference.md) · [All operations](https://skmtc.dev/withorb/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withorb/api-reference/revisions/816dfe734e2e/schema)