Create subscription alert

curl --request POST \
  --url https://api.withorb.com/v1/alerts/subscription_id/{subscription_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "thresholds": [
    {
      "value": 123
    }
  ],
  "metric_id": "<string>",
  "grouping_keys": [
    "<string>"
  ],
  "currency": "<string>",
  "price_filters": [
    {
      "values": [
        "<string>"
      ]
    }
  ],
  "threshold_overrides": [
    {
      "group_values": [
        "<string>"
      ],
      "thresholds": [
        {
          "value": 123
        }
      ]
    }
  ]
}
'

{
  "id": "<string>",
  "type": "\"usage_exceeded\", \"cost_exceeded\", \"credit_balance_depleted\", \"credit_balance_recovered\", or \"credit_balance_dropped\"",
  "created_at": "2023-11-07T05:31:56Z",
  "enabled": true,
  "thresholds": [
    {
      "value": 123
    }
  ],
  "customer": {
    "id": "<string>",
    "external_customer_id": "<string>"
  },
  "plan": {
    "id": "m2t5akQeh2obwxeU",
    "external_plan_id": "m2t5akQeh2obwxeU",
    "name": "Example plan",
    "plan_version": "<string>"
  },
  "subscription": {
    "id": "<string>"
  },
  "metric": {
    "id": "<string>"
  },
  "currency": "<string>",
  "license_type": {
    "id": "<string>"
  },
  "grouping_keys": [
    "<string>"
  ],
  "price_filters": [
    {
      "values": [
        "<string>"
      ]
    }
  ],
  "threshold_overrides": [
    {
      "group_values": [
        "<string>"
      ],
      "thresholds": [
        {
          "value": 123
        }
      ]
    }
  ],
  "balance_alert_status": [
    {
      "threshold_value": 123,
      "in_alert": true
    }
  ]
}

Alert

Create subscription alert

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.

POST

alerts

subscription_id

{subscription_id}

Create subscription alert

curl --request POST \
  --url https://api.withorb.com/v1/alerts/subscription_id/{subscription_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "thresholds": [
    {
      "value": 123
    }
  ],
  "metric_id": "<string>",
  "grouping_keys": [
    "<string>"
  ],
  "currency": "<string>",
  "price_filters": [
    {
      "values": [
        "<string>"
      ]
    }
  ],
  "threshold_overrides": [
    {
      "group_values": [
        "<string>"
      ],
      "thresholds": [
        {
          "value": 123
        }
      ]
    }
  ]
}
'

{
  "id": "<string>",
  "type": "\"usage_exceeded\", \"cost_exceeded\", \"credit_balance_depleted\", \"credit_balance_recovered\", or \"credit_balance_dropped\"",
  "created_at": "2023-11-07T05:31:56Z",
  "enabled": true,
  "thresholds": [
    {
      "value": 123
    }
  ],
  "customer": {
    "id": "<string>",
    "external_customer_id": "<string>"
  },
  "plan": {
    "id": "m2t5akQeh2obwxeU",
    "external_plan_id": "m2t5akQeh2obwxeU",
    "name": "Example plan",
    "plan_version": "<string>"
  },
  "subscription": {
    "id": "<string>"
  },
  "metric": {
    "id": "<string>"
  },
  "currency": "<string>",
  "license_type": {
    "id": "<string>"
  },
  "grouping_keys": [
    "<string>"
  ],
  "price_filters": [
    {
      "values": [
        "<string>"
      ]
    }
  ],
  "threshold_overrides": [
    {
      "group_values": [
        "<string>"
      ],
      "thresholds": [
        {
          "value": 123
        }
      ]
    }
  ],
  "balance_alert_status": [
    {
      "threshold_value": 123,
      "in_alert": true
    }
  ]
}

Authorizations

Authorization

string

header

required

API Keys can be issued in the Orb's web application.

Path Parameters

subscription_id

string

required

Body

application/json

thresholds

Threshold · object[]

required

The thresholds that define the values at which the alert will be triggered.

Show child attributes

type

enum<string>

required

The type of alert to create. This must be a valid alert type.

Available options:

usage_exceeded,

cost_exceeded

metric_id

string | null

The metric to track usage for.

grouping_keys

string[] | null

The property keys to group cost alerts by. Only applicable for cost_exceeded alerts.

currency

string | null

The case sensitive currency or custom pricing unit to use for grouped cost alerts. Required when grouping_keys is set.

price_filters

PriceFilter · object[] | null

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.

Show child attributes

threshold_overrides

ThresholdOverrideParams · object[] | null

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.

Show child attributes

Response

Created

Alerts within Orb 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.

string

required

Also referred to as alert_id in this documentation.

Example:

"XuxCbt7x9L82yyeF"

type

required

The type of alert. This must be a valid alert type.

Available options:

credit_balance_depleted,

credit_balance_dropped,

credit_balance_recovered

Example:

"\"usage_exceeded\", \"cost_exceeded\", \"credit_balance_depleted\", \"credit_balance_recovered\", or \"credit_balance_dropped\""

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 · object[] | null

required

The thresholds that define the conditions under which the alert will be triggered.

Show child attributes

customer

CustomerMinified · object

required

The customer the alert applies to.

Show child attributes

plan

PlanMinifiedWithVersion · object

required

The plan the alert applies to.

Show child attributes

subscription

SubscriptionMinified · object

required

The subscription the alert applies to.

Show child attributes

metric

BillableMetricMinified · object

required

The metric the alert applies to.

Show child attributes

currency

string | null

required

The name of the currency the credit balance or invoice cost is denominated in.

license_type

LicenseTypeMinified · object

The license type the alert applies to. Only present for license alerts.

Show child attributes

grouping_keys

string[] | null

The property keys to group cost alerts by. Only present for cost alerts with grouping enabled.

price_filters

PriceFilter · object[] | null

Filters scoping which prices are included in grouped cost alert evaluation.

Show child attributes

threshold_overrides

ThresholdOverride · object[] | null

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.

Show child attributes

balance_alert_status

BalanceAlertStatus · object[] | null

The current status of the alert. This field is only present for credit balance alerts.

Show child attributes

Create customer alert by external ID

Update alert

⌘I