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

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:



387
388
389
390
391
392
 
# File 'lib/orb/resources/customers.rb', line 387

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)

Returns:



13
14
15
 
# File 'lib/orb/resources/customers.rb', line 13

def balance_transactions
  @balance_transactions
end

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

Returns:



7
8
9
 
# File 'lib/orb/resources/customers.rb', line 7

def costs
  @costs
end

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

Returns:



10
11
12
 
# File 'lib/orb/resources/customers.rb', line 10

def credits
  @credits
end

Instance Method Details

#create(email: , name: , accounting_sync_configuration: nil, additional_emails: nil, auto_collection: nil, billing_address: nil, currency: nil, email_delivery: nil, external_customer_id: nil, hierarchy: nil, metadata: 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](/core-concepts##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](/events-and-metrics/customer-aliases) can be configured by setting ‘external_customer_id`

  • [Timezone localization](/essentials/timezones) can be configured on a per-customer basis by setting the ‘timezone` parameter

Parameters:

  • email (String) —

    A valid customer email, to be used for notifications. When Orb triggers payment

  • name (String) —

    The full name of the customer

  • accounting_sync_configuration (Orb::Models::NewAccountingSyncConfiguration, nil)
  • additional_emails (Array<String>, nil) —

    Additional email addresses for this customer. If populated, these email addresse

  • auto_collection (Boolean, nil) —

    Used to determine if invoices for this customer will automatically attempt to ch

  • billing_address (Orb::Models::AddressInput, nil)
  • currency (String, nil) —

    An ISO 4217 currency string used for the customer’s invoices and balance. If not

  • email_delivery (Boolean, nil)
  • external_customer_id (String, nil) —

    An optional user-defined ID for this customer resource, used throughout the syst

  • hierarchy (Orb::Models::CustomerHierarchyConfig, nil) —

    The hierarchical relationships for this customer.

  • metadata (Hash{Symbol=>String, nil}, nil) —

    User-specified key/value pairs for the resource. Individual keys can be removed

  • payment_provider (Symbol, Orb::Models::CustomerCreateParams::PaymentProvider, nil) —

    This is used for creating charges or invoices in an external system via Orb. Whe

  • payment_provider_id (String, nil) —

    The ID of this customer in an external payments solution, such as Stripe. This i

  • reporting_configuration (Orb::Models::NewReportingConfiguration, nil)
  • shipping_address (Orb::Models::AddressInput, nil)
  • tax_configuration (Orb::Models::NewAvalaraTaxConfiguration, Orb::Models::NewTaxJarConfiguration, Orb::Models::NewSphereConfiguration, nil)
  • tax_id (Orb::Models::CustomerTaxID, nil) —

    Tax IDs are commonly required to be displayed on customer invoices, which are ad

  • timezone (String, nil) —

    A timezone identifier from the IANA timezone database, such as ‘“America/Los_Ang

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

Returns:

See Also:



74
75
76
77
78
79
80
81
82
83
 
# File 'lib/orb/resources/customers.rb', line 74

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:



215
216
217
218
219
220
221
222
 
# File 'lib/orb/resources/customers.rb', line 215

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](/core-concepts#customer) for a full discussion of the Customer model.

Parameters:

Returns:

See Also:



239
240
241
242
243
244
245
246
 
# File 'lib/orb/resources/customers.rb', line 239

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](/events-and-metrics/customer-aliases)).

Note that the resource and semantics of this endpoint exactly mirror [Get Customer](fetch-customer).

Parameters:

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

Returns:

See Also:



262
263
264
265
266
267
268
269
 
# File 'lib/orb/resources/customers.rb', line 262

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](/api-reference/pagination).

See [Customer](/core-concepts##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:



177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/orb/resources/customers.rb', line 177

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



286
287
288
289
290
291
292
293
 
# File 'lib/orb/resources/customers.rb', line 286

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:



310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/orb/resources/customers.rb', line 310

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, billing_address: nil, currency: nil, email: nil, email_delivery: nil, external_customer_id: nil, hierarchy: nil, metadata: nil, name: 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`, and `additional_emails` of an existing customer. Other fields on a customer are currently immutable.

Parameters:

Returns:

See Also:



137
138
139
140
141
142
143
144
145
146
 
# File 'lib/orb/resources/customers.rb', line 137

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, billing_address: nil, currency: nil, email: nil, email_delivery: nil, external_customer_id: nil, hierarchy: nil, metadata: nil, name: 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](/events-and-metrics/customer-aliases)). Note that the resource and semantics of this endpoint exactly mirror [Update Customer](update-customer).

Parameters:

Returns:

See Also:



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

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