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:



295
296
297
 
# File 'lib/orb/resources/alerts.rb', line 295

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:



143
144
145
146
147
148
149
150
151
152
 
# File 'lib/orb/resources/alerts.rb', line 143

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:



178
179
180
181
182
183
184
185
186
187
 
# File 'lib/orb/resources/alerts.rb', line 178

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:



227
228
229
230
231
232
233
234
235
236
 
# File 'lib/orb/resources/alerts.rb', line 227

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

#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:



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

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:



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

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