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
        }
      ]
    }
  ]
}
'

import requests

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

payload = {
    "thresholds": [{ "value": 123 }],
    "metric_id": "<string>",
    "grouping_keys": ["<string>"],
    "currency": "<string>",
    "price_filters": [{ "values": ["<string>"] }],
    "threshold_overrides": [
        {
            "group_values": ["<string>"],
            "thresholds": [{ "value": 123 }]
        }
    ]
}
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>',
    grouping_keys: ['<string>'],
    currency: '<string>',
    price_filters: [{values: ['<string>']}],
    threshold_overrides: [{group_values: ['<string>'], thresholds: [{value: 123}]}]
  })
};

fetch('https://api.withorb.com/v1/alerts/subscription_id/{subscription_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/subscription_id/{subscription_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>',
    'grouping_keys' => [
        '<string>'
    ],
    'currency' => '<string>',
    'price_filters' => [
        [
                'values' => [
                                '<string>'
                ]
        ]
    ],
    'threshold_overrides' => [
        [
                'group_values' => [
                                '<string>'
                ],
                'thresholds' => [
                                [
                                                                'value' => 123
                                ]
                ]
        ]
    ]
  ]),
  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/subscription_id/{subscription_id}"

	payload := strings.NewReader("{\n  \"thresholds\": [\n    {\n      \"value\": 123\n    }\n  ],\n  \"metric_id\": \"<string>\",\n  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"threshold_overrides\": [\n    {\n      \"group_values\": [\n        \"<string>\"\n      ],\n      \"thresholds\": [\n        {\n          \"value\": 123\n        }\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/subscription_id/{subscription_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"thresholds\": [\n    {\n      \"value\": 123\n    }\n  ],\n  \"metric_id\": \"<string>\",\n  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"threshold_overrides\": [\n    {\n      \"group_values\": [\n        \"<string>\"\n      ],\n      \"thresholds\": [\n        {\n          \"value\": 123\n        }\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/alerts/subscription_id/{subscription_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  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"threshold_overrides\": [\n    {\n      \"group_values\": [\n        \"<string>\"\n      ],\n      \"thresholds\": [\n        {\n          \"value\": 123\n        }\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 subscription alert

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

Subscription level alerts can be one 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 subscription can have one cost_exceeded alert and one usage_exceeded alert per metric that is a part of the subscription.

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
        }
      ]
    }
  ]
}
'

import requests

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

payload = {
    "thresholds": [{ "value": 123 }],
    "metric_id": "<string>",
    "grouping_keys": ["<string>"],
    "currency": "<string>",
    "price_filters": [{ "values": ["<string>"] }],
    "threshold_overrides": [
        {
            "group_values": ["<string>"],
            "thresholds": [{ "value": 123 }]
        }
    ]
}
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>',
    grouping_keys: ['<string>'],
    currency: '<string>',
    price_filters: [{values: ['<string>']}],
    threshold_overrides: [{group_values: ['<string>'], thresholds: [{value: 123}]}]
  })
};

fetch('https://api.withorb.com/v1/alerts/subscription_id/{subscription_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/subscription_id/{subscription_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>',
    'grouping_keys' => [
        '<string>'
    ],
    'currency' => '<string>',
    'price_filters' => [
        [
                'values' => [
                                '<string>'
                ]
        ]
    ],
    'threshold_overrides' => [
        [
                'group_values' => [
                                '<string>'
                ],
                'thresholds' => [
                                [
                                                                'value' => 123
                                ]
                ]
        ]
    ]
  ]),
  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/subscription_id/{subscription_id}"

	payload := strings.NewReader("{\n  \"thresholds\": [\n    {\n      \"value\": 123\n    }\n  ],\n  \"metric_id\": \"<string>\",\n  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"threshold_overrides\": [\n    {\n      \"group_values\": [\n        \"<string>\"\n      ],\n      \"thresholds\": [\n        {\n          \"value\": 123\n        }\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/subscription_id/{subscription_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"thresholds\": [\n    {\n      \"value\": 123\n    }\n  ],\n  \"metric_id\": \"<string>\",\n  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"threshold_overrides\": [\n    {\n      \"group_values\": [\n        \"<string>\"\n      ],\n      \"thresholds\": [\n        {\n          \"value\": 123\n        }\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/alerts/subscription_id/{subscription_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  \"grouping_keys\": [\n    \"<string>\"\n  ],\n  \"currency\": \"<string>\",\n  \"price_filters\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"threshold_overrides\": [\n    {\n      \"group_values\": [\n        \"<string>\"\n      ],\n      \"thresholds\": [\n        {\n          \"value\": 123\n        }\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

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,

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

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 | 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 spend and grouped cost alert evaluation. Alerts use the price_id, item_id, and price_type fields only; the alert's pricing unit is reported by currency.

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

⌘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 subscription alert

Authorizations

Path Parameters

Body

Response