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:



527
528
529
530
531
532
 
# File 'lib/orb/resources/customers.rb', line 527

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

#create_portal_session(customer_id, expires_in_minutes: nil, invalidate_existing: nil, request_options: {}) ⇒ Orb::Models::CustomerCreatePortalSessionResponse

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

Creates a portal session for the customer, returning a short-lived URL that provides authenticated access to the customer's billing portal. The session expires after expires_in_minutes (default 60, max 180). By default, creating a new session invalidates any other active portal sessions for the customer; pass invalidate_existing=false to allow concurrent sessions.

Parameters:

  • customer_id (String)
  • expires_in_minutes (Integer) —

    Duration in minutes until the portal session expires. Defaults to 60. Maximum 18

  • invalidate_existing (Boolean) —

    When true (default), creating this session soft-deletes any other active portal

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

Returns:

See Also:



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

def create_portal_session(customer_id, params = {})
  parsed, options = Orb::CustomerCreatePortalSessionParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["customers/%1$s/portal_sessions", customer_id],
    body: parsed,
    model: Orb::Models::CustomerCreatePortalSessionResponse,
    options: options
  )
end

#create_portal_session_by_external_id(external_customer_id, expires_in_minutes: nil, invalidate_existing: nil, request_options: {}) ⇒ Orb::Models::CustomerCreatePortalSessionByExternalIDResponse

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

Creates a portal session for the customer, returning a short-lived URL that provides authenticated access to the customer's billing portal. The session expires after expires_in_minutes (default 60, max 180). By default, creating a new session invalidates any other active portal sessions for the customer; pass invalidate_existing=false to allow concurrent sessions.

Parameters:

  • external_customer_id (String)
  • expires_in_minutes (Integer) —

    Duration in minutes until the portal session expires. Defaults to 60. Maximum 18

  • invalidate_existing (Boolean) —

    When true (default), creating this session soft-deletes any other active portal

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

Returns:

See Also:



347
348
349
350
351
352
353
354
355
356
 
# File 'lib/orb/resources/customers.rb', line 347

def create_portal_session_by_external_id(external_customer_id, params = {})
  parsed, options = Orb::CustomerCreatePortalSessionByExternalIDParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["customers/external_customer_id/%1$s/portal_sessions", external_customer_id],
    body: parsed,
    model: Orb::Models::CustomerCreatePortalSessionByExternalIDResponse,
    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:



373
374
375
376
377
378
379
380
 
# File 'lib/orb/resources/customers.rb', line 373

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:



396
397
398
399
400
401
402
403
 
# File 'lib/orb/resources/customers.rb', line 396

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:



420
421
422
423
424
425
426
427
 
# File 'lib/orb/resources/customers.rb', line 420

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:



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

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:



513
514
515
516
517
518
519
520
521
522
 
# File 'lib/orb/resources/customers.rb', line 513

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