Class: Orb::Resources::Customers

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

Overview

A customer is a buyer of your products, and the other party to the billing relationship.

In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an external_customer_id with your own identifier. See Customer ID Aliases for further information about how these aliases work in Orb.

In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the payment_provider_id and the payment_provider enum field to express this mapping.

A customer also has a timezone (from the standard IANA timezone database), which defaults to your account's timezone. See Timezone localization for information on what this timezone parameter influences within Orb.

Defined Under Namespace

Classes: BalanceTransactions, Costs, Credits

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Customers

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

Parameters:



461
462
463
464
465
466
 
# File 'lib/orb/resources/customers.rb', line 461

def initialize(client:)
  @client = client
  @costs = Orb::Resources::Customers::Costs.new(client: client)
  @credits = Orb::Resources::Customers::Credits.new(client: client)
  @balance_transactions = Orb::Resources::Customers::BalanceTransactions.new(client: client)
end

Instance Attribute Details

#balance_transactions ⇒ Orb::Resources::Customers::BalanceTransactions (readonly)

A customer is a buyer of your products, and the other party to the billing relationship.

In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an external_customer_id with your own identifier. See Customer ID Aliases for further information about how these aliases work in Orb.

In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the payment_provider_id and the payment_provider enum field to express this mapping.

A customer also has a timezone (from the standard IANA timezone database), which defaults to your account's timezone. See Timezone localization for information on what this timezone parameter influences within Orb.

Returns:



69
70
71
 
# File 'lib/orb/resources/customers.rb', line 69

def balance_transactions
  @balance_transactions
end

#costs ⇒ Orb::Resources::Customers::Costs (readonly)

A customer is a buyer of your products, and the other party to the billing relationship.

In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an external_customer_id with your own identifier. See Customer ID Aliases for further information about how these aliases work in Orb.

In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the payment_provider_id and the payment_provider enum field to express this mapping.

A customer also has a timezone (from the standard IANA timezone database), which defaults to your account's timezone. See Timezone localization for information on what this timezone parameter influences within Orb.

Returns:



43
44
45
 
# File 'lib/orb/resources/customers.rb', line 43

def costs
  @costs
end

#credits ⇒ Orb::Resources::Customers::Credits (readonly)

The Credit Ledger Entry resource models prepaid credits within Orb.

Returns:



48
49
50
 
# File 'lib/orb/resources/customers.rb', line 48

def credits
  @credits
end

Instance Method Details

#create(email:, name:, accounting_sync_configuration: nil, additional_emails: nil, auto_collection: nil, auto_issuance: nil, billing_address: nil, currency: nil, email_delivery: nil, external_customer_id: nil, hierarchy: nil, metadata: nil, payment_configuration: nil, payment_provider: nil, payment_provider_id: nil, reporting_configuration: nil, shipping_address: nil, tax_configuration: nil, tax_id: nil, timezone: nil, request_options: {}) ⇒ Orb::Models::Customer

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

This operation is used to create an Orb customer, who is party to the core billing relationship. See Customer for an overview of the customer resource.

This endpoint is critical in the following Orb functionality:

  • Automated charges can be configured by setting payment_provider and payment_provider_id to automatically issue invoices
  • Customer ID Aliases can be configured by setting external_customer_id
  • Timezone localization can be configured on a per-customer basis by setting the timezone parameter

Parameters:

Returns:

See Also:



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

def create(params)
  parsed, options = Orb::CustomerCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "customers",
    body: parsed,
    model: Orb::Customer,
    options: options
  )
end

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

This performs a deletion of this customer, its subscriptions, and its invoices, provided the customer does not have any issued invoices. Customers with issued invoices cannot be deleted. This operation is irreversible. Note that this is a soft deletion, but the data will be inaccessible through the API and Orb dashboard.

For a hard-deletion, please reach out to the Orb team directly.

Note: This operation happens asynchronously and can be expected to take a few minutes to propagate to related resources. However, querying for the customer on subsequent GET requests while deletion is in process will reflect its deletion.

Parameters:

Returns:

  • (nil)

See Also:



283
284
285
286
287
288
289
290
 
# File 'lib/orb/resources/customers.rb', line 283

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

#fetch(customer_id, request_options: {}) ⇒ Orb::Models::Customer

This endpoint is used to fetch customer details given an identifier. If the Customer is in the process of being deleted, only the properties id and deleted: true will be returned.

See the Customer resource for a full discussion of the Customer model.

Parameters:

Returns:

See Also:



307
308
309
310
311
312
313
314
 
# File 'lib/orb/resources/customers.rb', line 307

def fetch(customer_id, params = {})
  @client.request(
    method: :get,
    path: ["customers/%1$s", customer_id],
    model: Orb::Customer,
    options: params[:request_options]
  )
end

#fetch_by_external_id(external_customer_id, request_options: {}) ⇒ Orb::Models::Customer

This endpoint is used to fetch customer details given an external_customer_id (see Customer ID Aliases).

Note that the resource and semantics of this endpoint exactly mirror Get Customer.

Parameters:

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

Returns:

See Also:



330
331
332
333
334
335
336
337
 
# File 'lib/orb/resources/customers.rb', line 330

def fetch_by_external_id(external_customer_id, params = {})
  @client.request(
    method: :get,
    path: ["customers/external_customer_id/%1$s", external_customer_id],
    model: Orb::Customer,
    options: params[:request_options]
  )
end

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

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

This endpoint returns a list of all customers for an account. The list of customers is ordered starting from the most recently created customer. This endpoint follows Orb's standardized pagination format.

See Customer for an overview of the customer model.

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

  • limit (Integer) —

    The number of items to fetch. Defaults to 20.

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

Returns:

See Also:



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/orb/resources/customers.rb', line 244

def list(params = {})
  parsed, options = Orb::CustomerListParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "customers",
    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::Customer,
    options: options
  )
end

#sync_payment_methods_from_gateway(customer_id, request_options: {}) ⇒ nil

Sync Orb's payment methods for the customer with their gateway.

This method can be called before taking an action that may cause the customer to be charged, ensuring that the most up-to-date payment method is charged.

Note: This functionality is currently only available for Stripe.

Parameters:

Returns:

  • (nil)

See Also:



354
355
356
357
358
359
360
361
 
# File 'lib/orb/resources/customers.rb', line 354

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

#sync_payment_methods_from_gateway_by_external_customer_id(external_customer_id, request_options: {}) ⇒ nil

Sync Orb's payment methods for the customer with their gateway.

This method can be called before taking an action that may cause the customer to be charged, ensuring that the most up-to-date payment method is charged.

Note: This functionality is currently only available for Stripe.

Parameters:

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

Returns:

  • (nil)

See Also:



378
379
380
381
382
383
384
385
386
387
388
 
# File 'lib/orb/resources/customers.rb', line 378

def sync_payment_methods_from_gateway_by_external_customer_id(external_customer_id, params = {})
  @client.request(
    method: :post,
    path: [
      "customers/external_customer_id/%1$s/sync_payment_methods_from_gateway",
      external_customer_id
    ],
    model: NilClass,
    options: params[:request_options]
  )
end

#update(customer_id, accounting_sync_configuration: nil, additional_emails: nil, auto_collection: nil, auto_issuance: nil, billing_address: nil, currency: nil, default_payment_method_id: nil, email: nil, email_delivery: nil, external_customer_id: nil, hierarchy: nil, metadata: nil, name: nil, payment_configuration: nil, payment_provider: nil, payment_provider_id: nil, reporting_configuration: nil, shipping_address: nil, tax_configuration: nil, tax_id: nil, request_options: {}) ⇒ Orb::Models::Customer

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

This endpoint can be used to update the payment_provider, payment_provider_id, name, email, email_delivery, tax_id, auto_collection, metadata, shipping_address, billing_address, additional_emails, and currency of an existing customer. currency can only be set if it has not already been set on the customer. Other fields on a customer are currently immutable.

Parameters:

Returns:

See Also:



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

def update(customer_id, params = {})
  parsed, options = Orb::CustomerUpdateParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["customers/%1$s", customer_id],
    body: parsed,
    model: Orb::Customer,
    options: options
  )
end

#update_by_external_id(id, accounting_sync_configuration: nil, additional_emails: nil, auto_collection: nil, auto_issuance: nil, billing_address: nil, currency: nil, default_payment_method_id: nil, email: nil, email_delivery: nil, external_customer_id: nil, hierarchy: nil, metadata: nil, name: nil, payment_configuration: nil, payment_provider: nil, payment_provider_id: nil, reporting_configuration: nil, shipping_address: nil, tax_configuration: nil, tax_id: nil, request_options: {}) ⇒ Orb::Models::Customer

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

This endpoint is used to update customer details given an external_customer_id (see Customer ID Aliases). Note that the resource and semantics of this endpoint exactly mirror Update Customer.

Parameters:

Returns:

See Also:



447
448
449
450
451
452
453
454
455
456
 
# File 'lib/orb/resources/customers.rb', line 447

def update_by_external_id(id, params = {})
  parsed, options = Orb::CustomerUpdateByExternalIDParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["customers/external_customer_id/%1$s", id],
    body: parsed,
    model: Orb::Customer,
    options: options
  )
end