Class: Orb::Resources::Customers::Credits::TopUps

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

Overview

The Credit Ledger Entry resource models prepaid credits within Orb.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ TopUps

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

Parameters:



238
239
240
 
# File 'lib/orb/resources/customers/credits/top_ups.rb', line 238

def initialize(client:)
  @client = client
end

Instance Method Details

#create(customer_id, amount:, currency:, invoice_settings:, per_unit_cost_basis:, threshold:, active_from: nil, expires_after: nil, expires_after_unit: nil, request_options: {}) ⇒ Orb::Models::Customers::Credits::TopUpCreateResponse

Some parameter documentations has been truncated, see Models::Customers::Credits::TopUpCreateParams for more details.

This endpoint allows you to create a new top-up for a specified customer's balance. While this top-up is active, the customer's balance will added in increments of the specified amount whenever the balance reaches the specified threshold.

If a top-up already exists for this customer in the same currency, the existing top-up will be replaced.

Parameters:

  • customer_id (String)
  • amount (String) —

    The amount to increment when the threshold is reached.

  • currency (String) —

    The currency or custom pricing unit to use for this top-up. If this is a real-wo

  • invoice_settings (Orb::Models::Customers::Credits::TopUpCreateParams::InvoiceSettings) —

    Settings for invoices generated by triggered top-ups.

  • per_unit_cost_basis (String) —

    How much, in the customer's currency, to charge for each unit.

  • threshold (String) —

    The threshold at which to trigger the top-up. If the balance is at or below this

  • active_from (Time, nil) —

    The date from which the top-up is active. If unspecified, the top-up is active i

  • expires_after (Integer, nil) —

    The number of days or months after which the top-up expires. If unspecified, it

  • expires_after_unit (Symbol, Orb::Models::Customers::Credits::TopUpCreateParams::ExpiresAfterUnit, nil) —

    The unit of expires_after.

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

Returns:

See Also:



46
47
48
49
50
51
52
53
54
55
 
# File 'lib/orb/resources/customers/credits/top_ups.rb', line 46

def create(customer_id, params)
  parsed, options = Orb::Customers::Credits::TopUpCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["customers/%1$s/credits/top_ups", customer_id],
    body: parsed,
    model: Orb::Models::Customers::Credits::TopUpCreateResponse,
    options: options
  )
end

#create_by_external_id(external_customer_id, amount:, currency:, invoice_settings:, per_unit_cost_basis:, threshold:, active_from: nil, expires_after: nil, expires_after_unit: nil, request_options: {}) ⇒ Orb::Models::Customers::Credits::TopUpCreateByExternalIDResponse

Some parameter documentations has been truncated, see Models::Customers::Credits::TopUpCreateByExternalIDParams for more details.

This endpoint allows you to create a new top-up for a specified customer's balance. While this top-up is active, the customer's balance will added in increments of the specified amount whenever the balance reaches the specified threshold.

If a top-up already exists for this customer in the same currency, the existing top-up will be replaced.

Parameters:

  • external_customer_id (String)
  • amount (String) —

    The amount to increment when the threshold is reached.

  • currency (String) —

    The currency or custom pricing unit to use for this top-up. If this is a real-wo

  • invoice_settings (Orb::Models::Customers::Credits::TopUpCreateByExternalIDParams::InvoiceSettings) —

    Settings for invoices generated by triggered top-ups.

  • per_unit_cost_basis (String) —

    How much, in the customer's currency, to charge for each unit.

  • threshold (String) —

    The threshold at which to trigger the top-up. If the balance is at or below this

  • active_from (Time, nil) —

    The date from which the top-up is active. If unspecified, the top-up is active i

  • expires_after (Integer, nil) —

    The number of days or months after which the top-up expires. If unspecified, it

  • expires_after_unit (Symbol, Orb::Models::Customers::Credits::TopUpCreateByExternalIDParams::ExpiresAfterUnit, nil) —

    The unit of expires_after.

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

Returns:

See Also:



157
158
159
160
161
162
163
164
165
166
 
# File 'lib/orb/resources/customers/credits/top_ups.rb', line 157

def create_by_external_id(external_customer_id, params)
  parsed, options = Orb::Customers::Credits::TopUpCreateByExternalIDParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["customers/external_customer_id/%1$s/credits/top_ups", external_customer_id],
    body: parsed,
    model: Orb::Models::Customers::Credits::TopUpCreateByExternalIDResponse,
    options: options
  )
end

#delete(top_up_id, customer_id:, request_options: {}) ⇒ nil

This deactivates the top-up and voids any invoices associated with pending credit blocks purchased through the top-up.

Parameters:

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

Returns:

  • (nil)

See Also:



106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/orb/resources/customers/credits/top_ups.rb', line 106

def delete(top_up_id, params)
  parsed, options = Orb::Customers::Credits::TopUpDeleteParams.dump_request(params)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :delete,
    path: ["customers/%1$s/credits/top_ups/%2$s", customer_id, top_up_id],
    model: NilClass,
    options: options
  )
end

#delete_by_external_id(top_up_id, external_customer_id:, request_options: {}) ⇒ nil

This deactivates the top-up and voids any invoices associated with pending credit blocks purchased through the top-up.

Parameters:

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

Returns:

  • (nil)

See Also:



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/orb/resources/customers/credits/top_ups.rb', line 180

def delete_by_external_id(top_up_id, params)
  parsed, options = Orb::Customers::Credits::TopUpDeleteByExternalIDParams.dump_request(params)
  external_customer_id =
    parsed.delete(:external_customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :delete,
    path: [
      "customers/external_customer_id/%1$s/credits/top_ups/%2$s",
      external_customer_id,
      top_up_id
    ],
    model: NilClass,
    options: options
  )
end

#list(customer_id, cursor: nil, limit: nil, request_options: {}) ⇒ Orb::Internal::Page<Orb::Models::Customers::Credits::TopUpListResponse>

Some parameter documentations has been truncated, see Models::Customers::Credits::TopUpListParams for more details.

This endpoint returns a list of a customer's active top-ups; a top-up that has been deactivated is not included. While a top-up is active, the customer's balance is increased by the top-up amount whenever it falls to the top-up's threshold.

The response also includes pagination_metadata, which lets the caller retrieve the next page of results if they exist.

Parameters:

  • customer_id (String)
  • cursor (String, nil) —

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

  • limit (Integer) —

    The number of items to fetch. Defaults to 20.

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

Returns:

See Also:



81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/orb/resources/customers/credits/top_ups.rb', line 81

def list(customer_id, params = {})
  parsed, options = Orb::Customers::Credits::TopUpListParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["customers/%1$s/credits/top_ups", customer_id],
    query: query,
    page: Orb::Internal::Page,
    model: Orb::Models::Customers::Credits::TopUpListResponse,
    options: options
  )
end

#list_by_external_id(external_customer_id, cursor: nil, limit: nil, request_options: {}) ⇒ Orb::Internal::Page<Orb::Models::Customers::Credits::TopUpListByExternalIDResponse>

Some parameter documentations has been truncated, see Models::Customers::Credits::TopUpListByExternalIDParams for more details.

This endpoint returns a list of a customer's active top-ups; a top-up that has been deactivated is not included. While a top-up is active, the customer's balance is increased by the top-up amount whenever it falls to the top-up's threshold.

The response also includes pagination_metadata, which lets the caller retrieve the next page of results if they exist.

Parameters:

  • external_customer_id (String)
  • cursor (String, nil) —

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

  • limit (Integer) —

    The number of items to fetch. Defaults to 20.

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

Returns:

See Also:



222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/orb/resources/customers/credits/top_ups.rb', line 222

def list_by_external_id(external_customer_id, params = {})
  parsed, options = Orb::Customers::Credits::TopUpListByExternalIDParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["customers/external_customer_id/%1$s/credits/top_ups", external_customer_id],
    query: query,
    page: Orb::Internal::Page,
    model: Orb::Models::Customers::Credits::TopUpListByExternalIDResponse,
    options: options
  )
end