Class: Dodopayments::Resources::CreditEntitlements

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

Defined Under Namespace

Classes: Balances

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ CreditEntitlements

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

Parameters:



385
386
387
388
 
# File 'lib/dodopayments/resources/credit_entitlements.rb', line 385

def initialize(client:)
  @client = client
  @balances = Dodopayments::Resources::CreditEntitlements::Balances.new(client: client)
end

Instance Attribute Details

#balances ⇒ Dodopayments::Resources::CreditEntitlements::Balances (readonly)

Returns:



7
8
9
 
# File 'lib/dodopayments/resources/credit_entitlements.rb', line 7

def balances
  @balances
end

Instance Method Details

#create(name:, overage_enabled:, precision:, rollover_enabled:, unit:, currency: nil, description: nil, expires_after_days: nil, max_rollover_count: nil, overage_behavior: nil, overage_limit: nil, price_per_unit: nil, rollover_percentage: nil, rollover_timeframe_count: nil, rollover_timeframe_interval: nil, request_options: {}) ⇒ Dodopayments::Models::CreditEntitlement

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

Credit entitlements define reusable credit templates that can be attached to products. Each entitlement defines how credits behave in terms of expiration, rollover, and overage.

Authentication

Requires an API key with Editor role.

Request Body

  • name - Human-readable name of the credit entitlement (1-255 characters, required)
  • description - Optional description (max 1000 characters)
  • precision - Decimal precision for credit amounts (0-10 decimal places)
  • unit - Unit of measurement for the credit (e.g., "API Calls", "Tokens", "Credits")
  • expires_after_days - Number of days after which credits expire (optional)
  • rollover_enabled - Whether unused credits can rollover to the next period
  • rollover_percentage - Percentage of unused credits that rollover (0-100)
  • rollover_timeframe_count - Count of timeframe periods for rollover limit
  • rollover_timeframe_interval - Interval type (day, week, month, year)
  • max_rollover_count - Maximum number of times credits can be rolled over
  • overage_enabled - Whether overage charges apply when credits run out (requires price_per_unit)
  • overage_limit - Maximum overage units allowed (optional)
  • currency - Currency for pricing (required if price_per_unit is set)
  • price_per_unit - Price per credit unit (decimal)

Responses

  • 201 Created - Credit entitlement created successfully, returns the full entitlement object
  • 422 Unprocessable Entity - Invalid request parameters or validation failure
  • 500 Internal Server Error - Database or server error

Business Logic

  • A unique ID with prefix cde_ is automatically generated for the entitlement
  • Created and updated timestamps are automatically set
  • Currency is required when price_per_unit is set
  • price_per_unit is required when overage_enabled is true
  • rollover_timeframe_count and rollover_timeframe_interval must both be set or both be null

Parameters:

  • name (String) —

    Name of the credit entitlement

  • overage_enabled (Boolean) —

    Whether overage charges are enabled when credits run out

  • precision (Integer) —

    Precision for credit amounts (0-10 decimal places)

  • rollover_enabled (Boolean) —

    Whether rollover is enabled for unused credits

  • unit (String) —

    Unit of measurement for the credit (e.g., "API Calls", "Tokens", "Credits")

  • currency (Symbol, Dodopayments::Models::Currency, nil) —

    Currency for pricing (required if price_per_unit is set)

  • description (String, nil) —

    Optional description of the credit entitlement

  • expires_after_days (Integer, nil) —

    Number of days after which credits expire (optional)

  • max_rollover_count (Integer, nil) —

    Maximum number of times credits can be rolled over

  • overage_behavior (Symbol, Dodopayments::Models::CbbOverageBehavior, nil) —

    Controls how overage is handled at billing cycle end.

  • overage_limit (Integer, nil) —

    Maximum overage units allowed (optional)

  • price_per_unit (String, nil) —

    Price per credit unit

  • rollover_percentage (Integer, nil) —

    Percentage of unused credits that can rollover (0-100)

  • rollover_timeframe_count (Integer, nil) —

    Count of timeframe periods for rollover limit

  • rollover_timeframe_interval (Symbol, Dodopayments::Models::TimeInterval, nil) —

    Interval type for rollover timeframe

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

Returns:

See Also:



93
94
95
96
97
98
99
100
101
102
 
# File 'lib/dodopayments/resources/credit_entitlements.rb', line 93

def create(params)
  parsed, options = Dodopayments::CreditEntitlementCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "credit-entitlements",
    body: parsed,
    model: Dodopayments::CreditEntitlement,
    options: options
  )
end

#delete(id, request_options: {}) ⇒ nil

Parameters:

Returns:

  • (nil)

See Also:



314
315
316
317
318
319
320
321
 
# File 'lib/dodopayments/resources/credit_entitlements.rb', line 314

def delete(id, params = {})
  @client.request(
    method: :delete,
    path: ["credit-entitlements/%1$s", id],
    model: NilClass,
    options: params[:request_options]
  )
end

#list(deleted: nil, page_number: nil, page_size: nil, request_options: {}) ⇒ Dodopayments::Internal::DefaultPageNumberPagination<Dodopayments::Models::CreditEntitlement>

Returns a paginated list of credit entitlements, allowing filtering of deleted entitlements. By default, only non-deleted entitlements are returned.

Authentication

Requires an API key with Viewer role or higher.

Query Parameters

  • page_size - Number of items per page (default: 10, max: 100)
  • page_number - Zero-based page number (default: 0)
  • deleted - Boolean flag to list deleted entitlements instead of active ones (default: false)

Responses

  • 200 OK - Returns a list of credit entitlements wrapped in a response object
  • 422 Unprocessable Entity - Invalid query parameters (e.g., page_size > 100)
  • 500 Internal Server Error - Database or server error

Business Logic

  • Results are ordered by creation date in descending order (newest first)
  • Only entitlements belonging to the authenticated business are returned
  • The deleted parameter controls visibility of soft-deleted entitlements
  • Pagination uses offset-based pagination (offset = page_number * page_size)

Parameters:

  • deleted (Boolean) —

    List deleted credit entitlements

  • 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:



292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/dodopayments/resources/credit_entitlements.rb', line 292

def list(params = {})
  parsed, options = Dodopayments::CreditEntitlementListParams.dump_request(params)
  query = Dodopayments::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "credit-entitlements",
    query: query,
    page: Dodopayments::Internal::DefaultPageNumberPagination,
    model: Dodopayments::CreditEntitlement,
    options: options
  )
end

#retrieve(id, request_options: {}) ⇒ Dodopayments::Models::CreditEntitlement

Returns the full details of a single credit entitlement including all configuration settings for expiration, rollover, and overage policies.

Authentication

Requires an API key with Viewer role or higher.

Path Parameters

  • id - The unique identifier of the credit entitlement (format: cde_...)

Responses

  • 200 OK - Returns the full credit entitlement object
  • 404 Not Found - Credit entitlement does not exist or does not belong to the authenticated business
  • 500 Internal Server Error - Database or server error

Business Logic

  • Only non-deleted credit entitlements can be retrieved through this endpoint
  • The entitlement must belong to the authenticated business (business_id check)
  • Deleted entitlements return a 404 error and must be retrieved via the list endpoint with deleted=true

Parameters:

Returns:

See Also:



138
139
140
141
142
143
144
145
 
# File 'lib/dodopayments/resources/credit_entitlements.rb', line 138

def retrieve(id, params = {})
  @client.request(
    method: :get,
    path: ["credit-entitlements/%1$s", id],
    model: Dodopayments::CreditEntitlement,
    options: params[:request_options]
  )
end

#undelete(id, request_options: {}) ⇒ nil

Undeletes a soft-deleted credit entitlement by clearing deleted_at, making it available again through standard list and get endpoints.

Authentication

Requires an API key with Editor role.

Path Parameters

  • id - The unique identifier of the credit entitlement to restore (format: cde_...)

Responses

  • 200 OK - Credit entitlement restored successfully
  • 500 Internal Server Error - Database error, entitlement not found, or entitlement is not deleted

Business Logic

  • Only deleted credit entitlements can be restored
  • The query filters for deleted_at IS NOT NULL, so non-deleted entitlements will result in 0 rows affected
  • If no rows are affected (entitlement doesn't exist, doesn't belong to business, or is not deleted), returns 500
  • The updated_at timestamp is automatically updated on successful restoration
  • Once restored, the entitlement becomes immediately available in the standard list and get endpoints
  • All configuration settings are preserved during delete/restore operations

Error Handling

This endpoint returns 500 Internal Server Error in several cases:

  • The credit entitlement does not exist
  • The credit entitlement belongs to a different business
  • The credit entitlement is not currently deleted (already active)

Callers should verify the entitlement exists and is deleted before calling this endpoint.

Parameters:

Returns:

  • (nil)

See Also:



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

def undelete(id, params = {})
  @client.request(
    method: :post,
    path: ["credit-entitlements/%1$s/undelete", id],
    model: NilClass,
    options: params[:request_options]
  )
end

#update(id, currency: nil, description: nil, expires_after_days: nil, max_rollover_count: nil, name: nil, overage_behavior: nil, overage_enabled: nil, overage_limit: nil, price_per_unit: nil, rollover_enabled: nil, rollover_percentage: nil, rollover_timeframe_count: nil, rollover_timeframe_interval: nil, unit: nil, request_options: {}) ⇒ nil

Allows partial updates to a credit entitlement's configuration. Only the fields provided in the request body will be updated; all other fields remain unchanged. This endpoint supports nullable fields using the double option pattern.

Authentication

Requires an API key with Editor role.

Path Parameters

  • id - The unique identifier of the credit entitlement to update (format: cde_...)

Request Body (all fields optional)

  • name - Human-readable name of the credit entitlement (1-255 characters)
  • description - Optional description (max 1000 characters)
  • unit - Unit of measurement for the credit (1-50 characters)

Note: precision cannot be modified after creation as it would invalidate existing grants.

  • expires_after_days - Number of days after which credits expire (use null to remove expiration)
  • rollover_enabled - Whether unused credits can rollover to the next period
  • rollover_percentage - Percentage of unused credits that rollover (0-100, nullable)
  • rollover_timeframe_count - Count of timeframe periods for rollover limit (nullable)
  • rollover_timeframe_interval - Interval type (day, week, month, year, nullable)
  • max_rollover_count - Maximum number of times credits can be rolled over (nullable)
  • overage_enabled - Whether overage charges apply when credits run out
  • overage_limit - Maximum overage units allowed (nullable)
  • currency - Currency for pricing (nullable)
  • price_per_unit - Price per credit unit (decimal, nullable)

Responses

  • 200 OK - Credit entitlement updated successfully
  • 404 Not Found - Credit entitlement does not exist or does not belong to the authenticated business
  • 422 Unprocessable Entity - Invalid request parameters or validation failure
  • 500 Internal Server Error - Database or server error

Business Logic

  • Only non-deleted credit entitlements can be updated
  • Fields set to null explicitly will clear the database value (using double option pattern)
  • The updated_at timestamp is automatically updated on successful modification
  • Changes take effect immediately but do not retroactively affect existing credit grants
  • The merged state is validated: currency required with price, rollover timeframe fields together, price required for overage

Parameters:

  • id (String) —

    Credit Entitlement ID

  • currency (Symbol, Dodopayments::Models::Currency, nil) —

    Currency for pricing

  • description (String, nil) —

    Optional description of the credit entitlement

  • expires_after_days (Integer, nil) —

    Number of days after which credits expire

  • max_rollover_count (Integer, nil) —

    Maximum number of times credits can be rolled over

  • name (String, nil) —

    Name of the credit entitlement

  • overage_behavior (Symbol, Dodopayments::Models::CbbOverageBehavior, nil) —

    Controls how overage is handled at billing cycle end.

  • overage_enabled (Boolean, nil) —

    Whether overage charges are enabled when credits run out

  • overage_limit (Integer, nil) —

    Maximum overage units allowed

  • price_per_unit (String, nil) —

    Price per credit unit

  • rollover_enabled (Boolean, nil) —

    Whether rollover is enabled for unused credits

  • rollover_percentage (Integer, nil) —

    Percentage of unused credits that can rollover (0-100)

  • rollover_timeframe_count (Integer, nil) —

    Count of timeframe periods for rollover limit

  • rollover_timeframe_interval (Symbol, Dodopayments::Models::TimeInterval, nil) —

    Interval type for rollover timeframe

  • unit (String, nil) —

    Unit of measurement for the credit (e.g., "API Calls", "Tokens", "Credits")

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

Returns:

  • (nil)

See Also:



241
242
243
244
245
246
247
248
249
250
 
# File 'lib/dodopayments/resources/credit_entitlements.rb', line 241

def update(id, params = {})
  parsed, options = Dodopayments::CreditEntitlementUpdateParams.dump_request(params)
  @client.request(
    method: :patch,
    path: ["credit-entitlements/%1$s", id],
    body: parsed,
    model: NilClass,
    options: options
  )
end