Class: Dodopayments::Resources::CreditEntitlements::Balances

Inherits:
Object
  • Object
show all
Defined in:
lib/dodopayments/resources/credit_entitlements/balances.rb,
sig/dodopayments/resources/credit_entitlements/balances.rbs

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Balances

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

Parameters:



302
303
304
 
# File 'lib/dodopayments/resources/credit_entitlements/balances.rb', line 302

def initialize(client:)
  @client = client
end

Instance Method Details

#create_ledger_entry(customer_id, credit_entitlement_id:, amount:, entry_type:, expires_at: nil, idempotency_key: nil, metadata: nil, reason: nil, request_options: {}) ⇒ Dodopayments::Models::CreditEntitlements::BalanceCreateLedgerEntryResponse

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

For credit entries, a new grant is created. For debit entries, credits are deducted from existing grants using FIFO (oldest first).

Authentication

Requires an API key with Editor role.

Path Parameters

  • credit_entitlement_id - The unique identifier of the credit entitlement
  • customer_id - The unique identifier of the customer

Request Body

  • entry_type - "credit" or "debit"
  • amount - Amount to credit or debit
  • reason - Optional human-readable reason
  • expires_at - Optional expiration for credited amount (only for credit type)
  • idempotency_key - Optional key to prevent duplicate entries

Responses

  • 201 Created - Ledger entry created successfully
  • 400 Bad Request - Invalid request (e.g., debit with insufficient balance)
  • 404 Not Found - Credit entitlement or customer not found
  • 409 Conflict - Idempotency key already exists
  • 500 Internal Server Error - Database or server error

Parameters:

  • customer_id (String) —

    Path param: Customer ID

  • credit_entitlement_id (String) —

    Path param: Credit Entitlement ID

  • amount (String) —

    Body param: Amount to credit or debit

  • entry_type (Symbol, Dodopayments::Models::CreditEntitlements::LedgerEntryType) —

    Body param: Entry type: credit or debit

  • expires_at (Time, nil) —

    Body param: Expiration for credited amount (only for credit type)

  • idempotency_key (String, nil) —

    Body param: Idempotency key to prevent duplicate entries

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

    Body param: Optional metadata (max 50 key-value pairs, key max 40 chars, value m

  • reason (String, nil) —

    Body param: Human-readable reason for the entry

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

Returns:

See Also:



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/dodopayments/resources/credit_entitlements/balances.rb', line 156

def create_ledger_entry(customer_id, params)
  parsed, options = Dodopayments::CreditEntitlements::BalanceCreateLedgerEntryParams.dump_request(params)
  credit_entitlement_id =
    parsed.delete(:credit_entitlement_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :post,
    path: [
      "credit-entitlements/%1$s/balances/%2$s/ledger-entries",
      credit_entitlement_id,
      customer_id
    ],
    body: parsed,
    model: Dodopayments::Models::CreditEntitlements::BalanceCreateLedgerEntryResponse,
    options: options
  )
end

#list(credit_entitlement_id, customer_id: nil, page_number: nil, page_size: nil, request_options: {}) ⇒ Dodopayments::Internal::DefaultPageNumberPagination<Dodopayments::Models::CreditEntitlements::CustomerCreditBalance>

Returns a paginated list of customer credit balances for the given credit entitlement.

Authentication

Requires an API key with Viewer role or higher.

Path Parameters

  • credit_entitlement_id - The unique identifier of the credit entitlement

Query Parameters

  • page_size - Number of items per page (default: 10, max: 100)
  • page_number - Zero-based page number (default: 0)
  • customer_id - Optional filter by specific customer

Responses

  • 200 OK - Returns list of customer balances
  • 404 Not Found - Credit entitlement not found
  • 500 Internal Server Error - Database or server error

Parameters:

  • credit_entitlement_id (String) —

    Credit Entitlement ID

  • customer_id (String) —

    Filter by specific customer ID

  • page_number (Integer) —

    Page number default is 0

  • page_size (Integer) —

    Page size default is 10 max is 100

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

Returns:

See Also:



88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/dodopayments/resources/credit_entitlements/balances.rb', line 88

def list(credit_entitlement_id, params = {})
  parsed, options = Dodopayments::CreditEntitlements::BalanceListParams.dump_request(params)
  query = Dodopayments::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["credit-entitlements/%1$s/balances", credit_entitlement_id],
    query: query,
    page: Dodopayments::Internal::DefaultPageNumberPagination,
    model: Dodopayments::CreditEntitlements::CustomerCreditBalance,
    options: options
  )
end

#list_grants(customer_id, credit_entitlement_id:, page_number: nil, page_size: nil, status: nil, request_options: {}) ⇒ Dodopayments::Internal::DefaultPageNumberPagination<Dodopayments::Models::CreditEntitlements::BalanceListGrantsResponse>

Returns a paginated list of credit grants with optional filtering by status.

Authentication

Requires an API key with Viewer role or higher.

Path Parameters

  • credit_entitlement_id - The unique identifier of the credit entitlement
  • customer_id - The unique identifier of the customer

Query Parameters

  • page_size - Number of items per page (default: 10, max: 100)
  • page_number - Zero-based page number (default: 0)
  • status - Filter by status: active, expired, depleted

Responses

  • 200 OK - Returns list of grants
  • 404 Not Found - Credit entitlement not found
  • 500 Internal Server Error - Database or server error

Parameters:

Returns:

See Also:



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/dodopayments/resources/credit_entitlements/balances.rb', line 215

def list_grants(customer_id, params)
  parsed, options = Dodopayments::CreditEntitlements::BalanceListGrantsParams.dump_request(params)
  query = Dodopayments::Internal::Util.encode_query_params(parsed)
  credit_entitlement_id =
    parsed.delete(:credit_entitlement_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["credit-entitlements/%1$s/balances/%2$s/grants", credit_entitlement_id, customer_id],
    query: query,
    page: Dodopayments::Internal::DefaultPageNumberPagination,
    model: Dodopayments::Models::CreditEntitlements::BalanceListGrantsResponse,
    options: options
  )
end

#list_ledger(customer_id, credit_entitlement_id:, end_date: nil, page_number: nil, page_size: nil, start_date: nil, transaction_type: nil, request_options: {}) ⇒ Dodopayments::Internal::DefaultPageNumberPagination<Dodopayments::Models::CreditEntitlements::CreditLedgerEntry>

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

Returns a paginated list of credit transaction history with optional filtering.

Authentication

Requires an API key with Viewer role or higher.

Path Parameters

  • credit_entitlement_id - The unique identifier of the credit entitlement
  • customer_id - The unique identifier of the customer

Query Parameters

  • page_size - Number of items per page (default: 10, max: 100)
  • page_number - Zero-based page number (default: 0)
  • transaction_type - Filter by transaction type
  • start_date - Filter entries from this date
  • end_date - Filter entries until this date

Responses

  • 200 OK - Returns list of ledger entries
  • 404 Not Found - Credit entitlement not found
  • 500 Internal Server Error - Database or server error

Parameters:

  • customer_id (String) —

    Path param: Customer ID

  • credit_entitlement_id (String) —

    Path param: Credit Entitlement ID

  • end_date (Time) —

    Query param: Filter by end date

  • page_number (Integer) —

    Query param: Page number default is 0

  • page_size (Integer) —

    Query param: Page size default is 10 max is 100

  • start_date (Time) —

    Query param: Filter by start date

  • transaction_type (String) —

    Query param: Filter by transaction type (snake_case: credit_added, credit_deduct

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

Returns:

See Also:



282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/dodopayments/resources/credit_entitlements/balances.rb', line 282

def list_ledger(customer_id, params)
  parsed, options = Dodopayments::CreditEntitlements::BalanceListLedgerParams.dump_request(params)
  query = Dodopayments::Internal::Util.encode_query_params(parsed)
  credit_entitlement_id =
    parsed.delete(:credit_entitlement_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["credit-entitlements/%1$s/balances/%2$s/ledger", credit_entitlement_id, customer_id],
    query: query,
    page: Dodopayments::Internal::DefaultPageNumberPagination,
    model: Dodopayments::CreditEntitlements::CreditLedgerEntry,
    options: options
  )
end

#retrieve(customer_id, credit_entitlement_id:, request_options: {}) ⇒ Dodopayments::Models::CreditEntitlements::CustomerCreditBalance

Returns the credit balance details for a specific customer and credit entitlement.

Authentication

Requires an API key with Viewer role or higher.

Path Parameters

  • credit_entitlement_id - The unique identifier of the credit entitlement
  • customer_id - The unique identifier of the customer

Responses

  • 200 OK - Returns the customer's balance
  • 404 Not Found - Credit entitlement or customer balance not found
  • 500 Internal Server Error - Database or server error

Parameters:

  • customer_id (String) —

    Customer ID

  • credit_entitlement_id (String) —

    Credit Entitlement ID

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

Returns:

See Also:



36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/dodopayments/resources/credit_entitlements/balances.rb', line 36

def retrieve(customer_id, params)
  parsed, options = Dodopayments::CreditEntitlements::BalanceRetrieveParams.dump_request(params)
  credit_entitlement_id =
    parsed.delete(:credit_entitlement_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["credit-entitlements/%1$s/balances/%2$s", credit_entitlement_id, customer_id],
    model: Dodopayments::CreditEntitlements::CustomerCreditBalance,
    options: options
  )
end