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:



321
322
323
 
# File 'lib/orb/resources/alerts.rb', line 321

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:



169
170
171
172
173
174
175
176
177
178
 
# File 'lib/orb/resources/alerts.rb', line 169

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:



204
205
206
207
208
209
210
211
212
213
 
# File 'lib/orb/resources/alerts.rb', line 204

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

Parameters:

Returns:

See Also:



253
254
255
256
257
258
259
260
261
262
 
# File 'lib/orb/resources/alerts.rb', line 253

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 trashes 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 trashed 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:



136
137
138
139
140
141
142
143
 
# File 'lib/orb/resources/alerts.rb', line 136

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:



279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/orb/resources/alerts.rb', line 279

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:



306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/orb/resources/alerts.rb', line 306

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:



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

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.

Parameters:

Returns:

See Also:



50
51
52
53
54
55
56
57
58
59
 
# File 'lib/orb/resources/alerts.rb', line 50

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