Class: Orb::Resources::Alerts

Inherits:
Object
  • Object
show all
Defined in:
lib/orb/resources/alerts.rb,
sig/orb/resources/alerts.rbs

Overview

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.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Alerts

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Alerts.

Parameters:



327
328
329
 
# File 'lib/orb/resources/alerts.rb', line 327

def initialize(client:)
  @client = client
end

Instance Method Details

#create_for_customer(customer_id, currency:, type:, thresholds: nil, request_options: {}) ⇒ Orb::Models::Alert

This endpoint creates a new alert to monitor a customer's credit balance. There are three types of alerts that can be scoped to customers: credit_balance_depleted, credit_balance_dropped, and credit_balance_recovered. Customers can have a maximum of one of each type of alert per credit balance currency. credit_balance_dropped alerts require a list of thresholds to be provided while credit_balance_depleted and credit_balance_recovered alerts do not require thresholds.

Parameters:

  • customer_id (String)
  • currency (String) —

    The case sensitive currency or custom pricing unit to use for this alert.

  • type (Symbol, Orb::Models::AlertCreateForCustomerParams::Type) —

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

  • thresholds (Array<Orb::Models::Threshold>, nil) —

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

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



172
173
174
175
176
177
178
179
180
181
 
# File 'lib/orb/resources/alerts.rb', line 172

def create_for_customer(customer_id, params)
  parsed, options = Orb::AlertCreateForCustomerParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["alerts/customer_id/%1$s", customer_id],
    body: parsed,
    model: Orb::Alert,
    options: options
  )
end

#create_for_external_customer(external_customer_id, currency:, type:, thresholds: nil, request_options: {}) ⇒ Orb::Models::Alert

This endpoint creates a new alert to monitor a customer's credit balance. There are three types of alerts that can be scoped to customers: credit_balance_depleted, credit_balance_dropped, and credit_balance_recovered. Customers can have a maximum of one of each type of alert per credit balance currency. credit_balance_dropped alerts require a list of thresholds to be provided while credit_balance_depleted and credit_balance_recovered alerts do not require thresholds.

Parameters:

Returns:

See Also:



207
208
209
210
211
212
213
214
215
216
 
# File 'lib/orb/resources/alerts.rb', line 207

def create_for_external_customer(external_customer_id, params)
  parsed, options = Orb::AlertCreateForExternalCustomerParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["alerts/external_customer_id/%1$s", external_customer_id],
    body: parsed,
    model: Orb::Alert,
    options: options
  )
end

#create_for_subscription(subscription_id, thresholds:, type:, currency: nil, grouping_keys: nil, metric_id: nil, price_filters: nil, threshold_overrides: nil, request_options: {}) ⇒ Orb::Models::Alert

Some parameter documentations has been truncated, see Models::AlertCreateForSubscriptionParams for more details.

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.

Parameters:

Returns:

See Also:



259
260
261
262
263
264
265
266
267
268
 
# File 'lib/orb/resources/alerts.rb', line 259

def create_for_subscription(subscription_id, params)
  parsed, options = Orb::AlertCreateForSubscriptionParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["alerts/subscription_id/%1$s", subscription_id],
    body: parsed,
    model: Orb::Alert,
    options: options
  )
end

#delete(alert_configuration_id, request_options: {}) ⇒ nil

This endpoint deletes a subscription or customer-scoped alert. The alert is soft-deleted: it stops firing immediately and no longer appears in fetch or list responses, while the underlying record is retained internally for audit.

Plan-level alerts cannot be deleted via the API — disable them instead (POST /v1/alerts/{alert_configuration_id}/disable). Their removal would need to be unwound from every subscription the alert was propagated to, which isn't supported yet.

Parameters:

  • alert_configuration_id (String)
  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



139
140
141
142
143
144
145
146
 
# File 'lib/orb/resources/alerts.rb', line 139

def delete(alert_configuration_id, params = {})
  @client.request(
    method: :delete,
    path: ["alerts/%1$s", alert_configuration_id],
    model: NilClass,
    options: params[:request_options]
  )
end

#disable(alert_configuration_id, subscription_id: nil, request_options: {}) ⇒ Orb::Models::Alert

This endpoint allows you to disable an alert. To disable a plan-level alert for a specific subscription, you must include the subscription_id. The subscription_id is not required for customer or subscription level alerts.

Parameters:

  • alert_configuration_id (String)
  • subscription_id (String, nil) —

    Used to update the status of a plan alert scoped to this subscription_id

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/orb/resources/alerts.rb', line 285

def disable(alert_configuration_id, params = {})
  parsed, options = Orb::AlertDisableParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :post,
    path: ["alerts/%1$s/disable", alert_configuration_id],
    query: query,
    model: Orb::Alert,
    options: options
  )
end

#enable(alert_configuration_id, subscription_id: nil, request_options: {}) ⇒ Orb::Models::Alert

This endpoint allows you to enable an alert. To enable a plan-level alert for a specific subscription, you must include the subscription_id. The subscription_id is not required for customer or subscription level alerts.

Parameters:

  • alert_configuration_id (String)
  • subscription_id (String, nil) —

    Used to update the status of a plan alert scoped to this subscription_id

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/orb/resources/alerts.rb', line 312

def enable(alert_configuration_id, params = {})
  parsed, options = Orb::AlertEnableParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :post,
    path: ["alerts/%1$s/enable", alert_configuration_id],
    query: query,
    model: Orb::Alert,
    options: options
  )
end

#list(created_at_gt: nil, created_at_gte: nil, created_at_lt: nil, created_at_lte: nil, cursor: nil, customer_id: nil, external_customer_id: nil, limit: nil, subscription_id: nil, request_options: {}) ⇒ Orb::Internal::Page<Orb::Models::Alert>

Some parameter documentations has been truncated, see Models::AlertListParams for more details.

This endpoint returns a list of alerts within Orb.

The request must specify one of customer_id, external_customer_id, or subscription_id.

If querying by subscription_id, the endpoint will return the subscription level alerts as well as the plan level alerts associated with the subscription.

The list of alerts is ordered starting from the most recently created alert. This endpoint follows Orb's standardized pagination format.

Parameters:

  • created_at_gt (Time, nil)
  • created_at_gte (Time, nil)
  • created_at_lt (Time, nil)
  • created_at_lte (Time, nil)
  • cursor (String, nil) —

    Cursor for pagination. This can be populated by the next_cursor value returned

  • customer_id (String, nil) —

    Fetch alerts scoped to this customer_id

  • external_customer_id (String, nil) —

    Fetch alerts scoped to this external_customer_id

  • limit (Integer) —

    The number of items to fetch. Defaults to 20.

  • subscription_id (String, nil) —

    Fetch alerts scoped to this subscription_id

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/orb/resources/alerts.rb', line 104

def list(params = {})
  parsed, options = Orb::AlertListParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "alerts",
    query: query.transform_keys(
      created_at_gt: "created_at[gt]",
      created_at_gte: "created_at[gte]",
      created_at_lt: "created_at[lt]",
      created_at_lte: "created_at[lte]"
    ),
    page: Orb::Internal::Page,
    model: Orb::Alert,
    options: options
  )
end

#retrieve(alert_id, request_options: {}) ⇒ Orb::Models::Alert

This endpoint retrieves an alert by its ID.

Parameters:

Returns:

See Also:



21
22
23
24
25
26
27
28
 
# File 'lib/orb/resources/alerts.rb', line 21

def retrieve(alert_id, params = {})
  @client.request(
    method: :get,
    path: ["alerts/%1$s", alert_id],
    model: Orb::Alert,
    options: params[:request_options]
  )
end

#update(alert_configuration_id, thresholds:, price_filters: nil, threshold_overrides: nil, request_options: {}) ⇒ Orb::Models::Alert

Some parameter documentations has been truncated, see Models::AlertUpdateParams for more details.

This endpoint updates the thresholds of an alert. On cost alerts it also updates price_filters, and on subscription-scoped grouped cost alerts threshold_overrides; omitting either leaves it unchanged, and an empty list clears it.

Parameters:

Returns:

See Also:



53
54
55
56
57
58
59
60
61
62
 
# File 'lib/orb/resources/alerts.rb', line 53

def update(alert_configuration_id, params)
  parsed, options = Orb::AlertUpdateParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["alerts/%1$s", alert_configuration_id],
    body: parsed,
    model: Orb::Alert,
    options: options
  )
end