Class: Dodopayments::Resources::Subscriptions

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

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Subscriptions

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

Parameters:



441
442
443
 
# File 'lib/dodopayments/resources/subscriptions.rb', line 441

def initialize(client:)
  @client = client
end

Instance Method Details

#cancel_change_plan(subscription_id, request_options: {}) ⇒ nil

Parameters:

Returns:

  • (nil)

See Also:



193
194
195
196
197
198
199
200
 
# File 'lib/dodopayments/resources/subscriptions.rb', line 193

def cancel_change_plan(subscription_id, params = {})
  @client.request(
    method: :delete,
    path: ["subscriptions/%1$s/change-plan/scheduled", subscription_id],
    model: NilClass,
    options: params[:request_options]
  )
end

#change_plan(subscription_id, product_id:, proration_billing_mode:, quantity:, adaptive_currency_fees_inclusive: nil, addons: nil, discount_code: nil, discount_codes: nil, effective_at: nil, metadata: nil, on_payment_failure: nil, request_options: {}) ⇒ nil

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

Parameters:

Returns:

  • (nil)

See Also:



234
235
236
237
238
239
240
241
242
243
 
# File 'lib/dodopayments/resources/subscriptions.rb', line 234

def change_plan(subscription_id, params)
  parsed, options = Dodopayments::SubscriptionChangePlanParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["subscriptions/%1$s/change-plan", subscription_id],
    body: parsed,
    model: NilClass,
    options: options
  )
end

#charge(subscription_id, product_price:, adaptive_currency_fees_inclusive: nil, customer_balance_config: nil, metadata: nil, product_currency: nil, product_description: nil, request_options: {}) ⇒ Dodopayments::Models::SubscriptionChargeResponse

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

Parameters:

  • subscription_id (String) —

    Subscription Id

  • product_price (Integer) —

    The product price. Represented in the lowest denomination of the currency (e.g.,

  • adaptive_currency_fees_inclusive (Boolean, nil) —

    Whether adaptive currency fees should be included in the product_price (true) or

  • customer_balance_config (Dodopayments::Models::SubscriptionChargeParams::CustomerBalanceConfig, nil) —

    Specify how customer balance is used for the payment

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

    Metadata for the payment. If not passed, the metadata of the subscription will b

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

    Optional currency of the product price. If not specified, defaults to the curren

  • product_description (String, nil) —

    Optional product description override for billing and line items.

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

Returns:

See Also:



269
270
271
272
273
274
275
276
277
278
 
# File 'lib/dodopayments/resources/subscriptions.rb', line 269

def charge(subscription_id, params)
  parsed, options = Dodopayments::SubscriptionChargeParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["subscriptions/%1$s/charge", subscription_id],
    body: parsed,
    model: Dodopayments::Models::SubscriptionChargeResponse,
    options: options
  )
end

#create(billing:, customer:, product_id:, quantity:, addons: nil, allowed_payment_method_types: nil, billing_currency: nil, customer_business_name: nil, discount_code: nil, discount_codes: nil, force_3ds: nil, mandate_min_amount_inr_paise: nil, metadata: nil, on_demand: nil, one_time_product_cart: nil, payment_link: nil, payment_method_id: nil, redirect_immediately: nil, require_phone_number: nil, return_url: nil, short_link: nil, show_saved_payment_methods: nil, tax_id: nil, trial_period_days: nil, request_options: {}) ⇒ Dodopayments::Models::SubscriptionCreateResponse

Deprecated.

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

Parameters:

  • billing (Dodopayments::Models::BillingAddress) —

    Billing address information for the subscription

  • customer (Dodopayments::Models::AttachExistingCustomer, Dodopayments::Models::NewCustomer) —

    Customer details for the subscription

  • product_id (String) —

    Unique identifier of the product to subscribe to

  • quantity (Integer) —

    Number of units to subscribe for. Must be at least 1.

  • addons (Array<Dodopayments::Models::AttachAddon>, nil) —

    Attach addons to this subscription

  • allowed_payment_method_types (Array<Symbol, Dodopayments::Models::PaymentMethodTypes>, nil) —

    List of payment methods allowed during checkout.

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

    Fix the currency in which the end customer is billed.

  • customer_business_name (String, nil) —

    Optional business / legal name associated with the tax id. When provided

  • discount_code (String, nil) —

    DEPRECATED: Use discount_codes instead. Cannot be used together with discount_co

  • discount_codes (Array<String>, nil) —

    Stacked discount codes to apply, in order of application. Max 20.

  • force_3ds (Boolean, nil) —

    Override merchant default 3DS behaviour for this subscription

  • mandate_min_amount_inr_paise (Integer, nil) —

    Override the merchant-level mandate floor (in INR paise) for INR

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

    Additional metadata for the subscription

  • on_demand (Dodopayments::Models::OnDemandSubscription, nil)
  • one_time_product_cart (Array<Dodopayments::Models::OneTimeProductCartItem>, nil) —

    List of one time products that will be bundled with the first payment for this s

  • payment_link (Boolean, nil) —

    If true, generates a payment link.

  • payment_method_id (String, nil) —

    Optional payment method ID to use for this subscription.

  • redirect_immediately (Boolean) —

    If true, redirects the customer immediately after payment completion

  • require_phone_number (Boolean) —

    If true, the customer's phone number is required to create this subscription.

  • return_url (String, nil) —

    Optional URL to redirect after successful subscription creation

  • short_link (Boolean, nil) —

    If true, returns a shortened payment link.

  • show_saved_payment_methods (Boolean) —

    Display saved payment methods of a returning customer

  • tax_id (String, nil) —

    Tax ID in case the payment is B2B. If tax id validation fails the payment creati

  • trial_period_days (Integer, nil) —

    Optional trial period in days

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

Returns:

See Also:



66
67
68
69
70
71
72
73
74
75
 
# File 'lib/dodopayments/resources/subscriptions.rb', line 66

def create(params)
  parsed, options = Dodopayments::SubscriptionCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "subscriptions",
    body: parsed,
    model: Dodopayments::Models::SubscriptionCreateResponse,
    options: options
  )
end

#list(brand_id: nil, created_at_gte: nil, created_at_lte: nil, customer_id: nil, page_number: nil, page_size: nil, product_id: nil, status: nil, request_options: {}) ⇒ Dodopayments::Internal::DefaultPageNumberPagination<Dodopayments::Models::SubscriptionListResponse>

Parameters:

  • brand_id (String) —

    filter by Brand id

  • created_at_gte (Time) —

    Get events after this created time

  • created_at_lte (Time) —

    Get events created before this time

  • customer_id (String) —

    Filter by customer id

  • page_number (Integer) —

    Page number default is 0

  • page_size (Integer) —

    Page size default is 10 max is 100

  • product_id (String) —

    Filter by product id

  • status (Symbol, Dodopayments::Models::SubscriptionListParams::Status) —

    Filter by status

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

Returns:

See Also:



171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/dodopayments/resources/subscriptions.rb', line 171

def list(params = {})
  parsed, options = Dodopayments::SubscriptionListParams.dump_request(params)
  query = Dodopayments::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "subscriptions",
    query: query,
    page: Dodopayments::Internal::DefaultPageNumberPagination,
    model: Dodopayments::Models::SubscriptionListResponse,
    options: options
  )
end

#preview_change_plan(subscription_id, product_id:, proration_billing_mode:, quantity:, adaptive_currency_fees_inclusive: nil, addons: nil, discount_code: nil, discount_codes: nil, effective_at: nil, metadata: nil, on_payment_failure: nil, request_options: {}) ⇒ Dodopayments::Models::SubscriptionPreviewChangePlanResponse

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

Parameters:

Returns:

See Also:



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

def preview_change_plan(subscription_id, params)
  parsed, options = Dodopayments::SubscriptionPreviewChangePlanParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["subscriptions/%1$s/change-plan/preview", subscription_id],
    body: parsed,
    model: Dodopayments::Models::SubscriptionPreviewChangePlanResponse,
    options: options
  )
end

#retrieve(subscription_id, request_options: {}) ⇒ Dodopayments::Models::Subscription

Parameters:

Returns:

See Also:



86
87
88
89
90
91
92
93
 
# File 'lib/dodopayments/resources/subscriptions.rb', line 86

def retrieve(subscription_id, params = {})
  @client.request(
    method: :get,
    path: ["subscriptions/%1$s", subscription_id],
    model: Dodopayments::Subscription,
    options: params[:request_options]
  )
end

#retrieve_credit_usage(subscription_id, request_options: {}) ⇒ Dodopayments::Models::SubscriptionRetrieveCreditUsageResponse

Parameters:

Returns:

See Also:



332
333
334
335
336
337
338
339
 
# File 'lib/dodopayments/resources/subscriptions.rb', line 332

def retrieve_credit_usage(subscription_id, params = {})
  @client.request(
    method: :get,
    path: ["subscriptions/%1$s/credit-usage", subscription_id],
    model: Dodopayments::Models::SubscriptionRetrieveCreditUsageResponse,
    options: params[:request_options]
  )
end

#retrieve_usage_history(subscription_id, end_date: nil, meter_id: nil, page_number: nil, page_size: nil, start_date: nil, request_options: {}) ⇒ Dodopayments::Internal::DefaultPageNumberPagination<Dodopayments::Models::SubscriptionRetrieveUsageHistoryResponse>

Get detailed usage history for a subscription that includes usage-based billing (metered components). This endpoint provides insights into customer usage patterns and billing calculations over time.

What You'll Get:

  • Billing periods: Each item represents a billing cycle with start and end dates
  • Meter usage: Detailed breakdown of usage for each meter configured on the subscription
  • Usage calculations: Total units consumed, free threshold units, and chargeable units
  • Historical tracking: Complete audit trail of usage-based charges

Use Cases:

  • Customer support: Investigate billing questions and usage discrepancies
  • Usage analytics: Analyze customer consumption patterns over time
  • Billing transparency: Provide customers with detailed usage breakdowns
  • Revenue optimization: Identify usage trends to optimize pricing strategies

Filtering Options:

  • Date range filtering: Get usage history for specific time periods
  • Meter-specific filtering: Focus on usage for a particular meter
  • Pagination: Navigate through large usage histories efficiently

Important Notes:

  • Only returns data for subscriptions with usage-based (metered) components
  • Usage history is organized by billing periods (subscription cycles)
  • Free threshold units are calculated and displayed separately from chargeable units
  • Historical data is preserved even if meter configurations change

Example Query Patterns:

  • Get last 3 months: ?start_date=2024-01-01T00:00:00Z&end_date=2024-03-31T23:59:59Z
  • Filter by meter: ?meter_id=mtr_api_requests
  • Paginate results: ?page_size=20&page_number=1
  • Recent usage: ?start_date=2024-03-01T00:00:00Z (from March 1st to now)

Parameters:

  • subscription_id (String) —

    Unique subscription identifier

  • end_date (Time, nil) —

    Filter by end date (inclusive)

  • meter_id (String, nil) —

    Filter by specific meter ID

  • page_number (Integer, nil) —

    Page number (default: 0)

  • page_size (Integer, nil) —

    Page size (default: 10, max: 100)

  • start_date (Time, nil) —

    Filter by start date (inclusive)

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

Returns:

See Also:



403
404
405
406
407
408
409
410
411
412
413
414
 
# File 'lib/dodopayments/resources/subscriptions.rb', line 403

def retrieve_usage_history(subscription_id, params = {})
  parsed, options = Dodopayments::SubscriptionRetrieveUsageHistoryParams.dump_request(params)
  query = Dodopayments::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["subscriptions/%1$s/usage-history", subscription_id],
    query: query,
    page: Dodopayments::Internal::DefaultPageNumberPagination,
    model: Dodopayments::Models::SubscriptionRetrieveUsageHistoryResponse,
    options: options
  )
end

#update(subscription_id, billing: nil, cancel_at_next_billing_date: nil, cancel_reason: nil, cancellation_comment: nil, cancellation_feedback: nil, credit_entitlement_cart: nil, customer_business_name: nil, customer_name: nil, disable_on_demand: nil, metadata: nil, next_billing_date: nil, status: nil, subscription_period_count: nil, subscription_period_interval: nil, tax_id: nil, request_options: {}) ⇒ Dodopayments::Models::Subscription

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

Parameters:

Returns:

See Also:



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

def update(subscription_id, params = {})
  parsed, options = Dodopayments::SubscriptionUpdateParams.dump_request(params)
  @client.request(
    method: :patch,
    path: ["subscriptions/%1$s", subscription_id],
    body: parsed,
    model: Dodopayments::Subscription,
    options: options
  )
end

#update_payment_method(subscription_id, payment_method:, request_options: {}) ⇒ Dodopayments::Models::SubscriptionUpdatePaymentMethodResponse

Parameters:

Returns:

See Also:



427
428
429
430
431
432
433
434
435
436
 
# File 'lib/dodopayments/resources/subscriptions.rb', line 427

def update_payment_method(subscription_id, params)
  parsed, options = Dodopayments::SubscriptionUpdatePaymentMethodParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["subscriptions/%1$s/update-payment-method", subscription_id],
    body: parsed[:payment_method],
    model: Dodopayments::Models::SubscriptionUpdatePaymentMethodResponse,
    options: options
  )
end