Class: Orb::Resources::Customers::BalanceTransactions

Inherits:
Object
  • Object
show all
Defined in:
lib/orb/resources/customers/balance_transactions.rb,
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.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ BalanceTransactions

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

Parameters:



121
122
123
 
# File 'lib/orb/resources/customers/balance_transactions.rb', line 121

def initialize(client:)
  @client = client
end

Instance Method Details

#create(customer_id, amount:, type:, description: nil, request_options: {}) ⇒ Orb::Models::Customers::BalanceTransactionCreateResponse

Creates an immutable balance transaction that updates the customer's balance and returns back the newly created transaction.

Parameters:

Returns:

See Also:



43
44
45
46
47
48
49
50
51
52
 
# File 'lib/orb/resources/customers/balance_transactions.rb', line 43

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

#list(customer_id, cursor: nil, limit: nil, operation_time_gt: nil, operation_time_gte: nil, operation_time_lt: nil, operation_time_lte: nil, request_options: {}) ⇒ Orb::Internal::Page<Orb::Models::Customers::BalanceTransactionListResponse>

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

The customer balance

The customer balance is an amount in the customer's currency, which Orb automatically applies to subsequent invoices. This balance can be adjusted manually via Orb's webapp on the customer details page. You can use this balance to provide a fixed mid-period credit to the customer. Commonly, this is done due to system downtime/SLA violation, or an adhoc adjustment discussed with the customer.

If the balance is a positive value at the time of invoicing, it represents that the customer has credit that should be used to offset the amount due on the next issued invoice. In this case, Orb will automatically reduce the next invoice by the balance amount, and roll over any remaining balance if the invoice is fully discounted.

If the balance is a negative value at the time of invoicing, Orb will increase the invoice's amount due with a positive adjustment, and reset the balance to 0.

This endpoint retrieves all customer balance transactions in reverse chronological order for a single customer, providing a complete audit trail of all adjustments and invoice applications.

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.

  • operation_time_gt (Time, nil)
  • operation_time_gte (Time, nil)
  • operation_time_lt (Time, nil)
  • operation_time_lte (Time, nil)
  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/orb/resources/customers/balance_transactions.rb', line 100

def list(customer_id, params = {})
  parsed, options = Orb::Customers::BalanceTransactionListParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["customers/%1$s/balance_transactions", customer_id],
    query: query.transform_keys(
      operation_time_gt: "operation_time[gt]",
      operation_time_gte: "operation_time[gte]",
      operation_time_lt: "operation_time[lt]",
      operation_time_lte: "operation_time[lte]"
    ),
    page: Orb::Internal::Page,
    model: Orb::Models::Customers::BalanceTransactionListResponse,
    options: options
  )
end