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

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

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}, 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