Create plan alert

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

import requests

url = "https://api.withorb.com/v1/alerts/plan_id/{plan_id}"

payload = {
    "thresholds": [{ "value": 123 }],
    "metric_id": "<string>",
    "plan_version": 123,
    "grouping_keys": ["<string>"],
    "currency": "<string>",
    "price_filters": [{ "values": ["<string>"] }]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    thresholds: [{value: 123}],
    metric_id: '<string>',
    plan_version: 123,
    grouping_keys: ['<string>'],
    currency: '<string>',
    price_filters: [{values: ['<string>']}]
  })
};

fetch('https://api.withorb.com/v1/alerts/plan_id/{plan_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.withorb.com/v1/alerts/plan_id/{plan_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'thresholds' => [
        [
                'value' => 123
        ]
    ],
    'metric_id' => '<string>',
    'plan_version' => 123,
    'grouping_keys' => [
        '<string>'
    ],
    'currency' => '<string>',
    'price_filters' => [
        [
                'values' => [
                                '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withorb.com/v1/alerts/plan_id/{plan_id}"

	payload := strings.NewReader("{\n  \"thresholds\": [\n    {\n      \"value\": 123\n    }\n  ],\n  \"metric_id\": \"<string>\",\n  \"plan_version\": 123,\n  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.withorb.com/v1/alerts/plan_id/{plan_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"thresholds\": [\n    {\n      \"value\": 123\n    }\n  ],\n  \"metric_id\": \"<string>\",\n  \"plan_version\": 123,\n  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/alerts/plan_id/{plan_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"thresholds\": [\n    {\n      \"value\": 123\n    }\n  ],\n  \"metric_id\": \"<string>\",\n  \"plan_version\": 123,\n  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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
    }
  ]
}

{
  "type": "https://docs.withorb.com/reference/error-responses#400-constraint-violation",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
  "status": 401,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#404-feature-not-available",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
  "status": 409,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#413-request-too-large",
  "status": 413,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
  "status": 429,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
  "status": 123,
  "detail": "<string>",
  "title": "<string>"
}

Alert

Create plan alert

This endpoint is used to create alerts at the plan level. Plan level alerts are automatically propagated to all subscriptions associated with the plan. These alerts are scoped to a specific plan version; if no version is specified, the active plan version is used.

Plan level alerts can be of three types: usage_exceeded, cost_exceeded, or spend_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. A spend_exceeded alert is triggered when the rated spend (the pricing subtotal, before invoice-level adjustments and credits) denominated in the alert’s currency exceeds predefined thresholds during the current billing cycle; price_filters can scope which prices contribute. Each plan can have one cost_exceeded alert and one usage_exceeded alert per metric that is a part of the plan.

POST

alerts

plan_id

{plan_id}

Create plan alert

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

import requests

url = "https://api.withorb.com/v1/alerts/plan_id/{plan_id}"

payload = {
    "thresholds": [{ "value": 123 }],
    "metric_id": "<string>",
    "plan_version": 123,
    "grouping_keys": ["<string>"],
    "currency": "<string>",
    "price_filters": [{ "values": ["<string>"] }]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    thresholds: [{value: 123}],
    metric_id: '<string>',
    plan_version: 123,
    grouping_keys: ['<string>'],
    currency: '<string>',
    price_filters: [{values: ['<string>']}]
  })
};

fetch('https://api.withorb.com/v1/alerts/plan_id/{plan_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.withorb.com/v1/alerts/plan_id/{plan_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'thresholds' => [
        [
                'value' => 123
        ]
    ],
    'metric_id' => '<string>',
    'plan_version' => 123,
    'grouping_keys' => [
        '<string>'
    ],
    'currency' => '<string>',
    'price_filters' => [
        [
                'values' => [
                                '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withorb.com/v1/alerts/plan_id/{plan_id}"

	payload := strings.NewReader("{\n  \"thresholds\": [\n    {\n      \"value\": 123\n    }\n  ],\n  \"metric_id\": \"<string>\",\n  \"plan_version\": 123,\n  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.withorb.com/v1/alerts/plan_id/{plan_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"thresholds\": [\n    {\n      \"value\": 123\n    }\n  ],\n  \"metric_id\": \"<string>\",\n  \"plan_version\": 123,\n  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/alerts/plan_id/{plan_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"thresholds\": [\n    {\n      \"value\": 123\n    }\n  ],\n  \"metric_id\": \"<string>\",\n  \"plan_version\": 123,\n  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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
    }
  ]
}

{
  "type": "https://docs.withorb.com/reference/error-responses#400-constraint-violation",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
  "status": 401,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#404-feature-not-available",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
  "status": 409,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#413-request-too-large",
  "status": 413,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
  "status": 429,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
  "status": 123,
  "detail": "<string>",
  "title": "<string>"
}

Authorizations

Authorization

string

header

required

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

Path Parameters

plan_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,

spend_exceeded

metric_id

string | null

The metric to track usage for.

plan_version

integer | null

The plan version to create alerts for. If not specified, the default will be the plan's active plan version.

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 the alert is denominated in. Required for spend_exceeded alerts and when grouping_keys is set.

price_filters

PriceFilter · object[] | null

Filters to scope which prices are included in alert evaluation. Supports filtering by price_id, item_id, or price_type with includes/excludes operators. Only applicable to spend_exceeded alerts and to cost_exceeded alerts with grouping_keys 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 | null

required

The customer the alert applies to.

Show child attributes

plan

PlanMinifiedWithVersion · object | null

required

The plan the alert applies to.

Show child attributes

subscription

SubscriptionMinified · object | null

required

The subscription the alert applies to.

Show child attributes

metric

BillableMetricMinified · object | null

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 | null

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

Create subscription alert

⌘I

API documentation

Alert

Coupon

Credit

Credit note

Customer

Dimensional Price Group

Event

Invoice

Item

LicenseType

License

Metric

Availability

Plan

Price

Subscription Change

Subscription

Price interval

Create plan alert

Authorizations

Path Parameters

Body

Response