dodopayments 2.32.2 → 2.34.0

data/rbi/dodopayments/models/payment.rbi

@@ -48,6 +48,12 @@ module Dodopayments
       sig { returns(T::Array[Dodopayments::Dispute]) }
       attr_accessor :disputes
 
+      # True when this payment also bills metered usage or credit overage. The usage is
+      # for the billing cycle before the service period, not for the service period. The
+      # value is set for each payment status. It is false when `charge_type` is null.
+      sig { returns(T::Boolean) }
+      attr_accessor :includes_usage
+
       # True when one payment starts more than one subscription. Read this field to find
       # the payment type. Do not read the length of `subscription_ids`. Do not read
       # `subscription_id` for null.
@@ -82,6 +88,17 @@ module Dodopayments
       sig { returns(Integer) }
       attr_accessor :retry_attempt
 
+      # The service period of each subscription that this payment pays for. The order is
+      # the same as `subscription_ids`. For a plan change charge, the period starts at
+      # the plan change and ends at the next billing date. The list is empty unless the
+      # payment status is `succeeded`. The list is also empty for a one-time payment, an
+      # on-demand charge, or a payment method update. The list is set for `new`,
+      # `renewal` and `plan_change` charges that succeeded. It can be empty for some
+      # zero-amount payments. A `renewal` with no entry for its subscription bills usage
+      # only. That payment does not extend the service period.
+      sig { returns(T::Array[Dodopayments::SubscriptionServicePeriod]) }
+      attr_accessor :service_periods
+
       # The amount that will be credited to your Dodo balance after currency conversion
       # and processing. Especially relevant for adaptive pricing where the customer's
       # payment currency differs from your settlement currency.
@@ -106,6 +123,18 @@ module Dodopayments
       sig { returns(Integer) }
       attr_accessor :total_amount
 
+      # Expiry month of the card, as two digits from `01` to `12`. For Apple Pay and
+      # Google Pay, this is the expiry of the wallet token, which can differ from the
+      # expiry of the physical card.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :card_exp_month
+
+      # Expiry year of the card, as four digits, for example `2029`. For Apple Pay and
+      # Google Pay, this is the expiry of the wallet token, which can differ from the
+      # expiry of the physical card.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :card_exp_year
+
       # Cardholder name
       sig { returns(T.nilable(String)) }
       attr_accessor :card_holder_name
@@ -118,14 +147,22 @@ module Dodopayments
       sig { returns(T.nilable(String)) }
       attr_accessor :card_last_four
 
-      # Card network like VISA, MASTERCARD etc.
+      # Card network, in lowercase, for example `visa`, `mastercard` or `amex`. Older
+      # payments can carry other casing.
       sig { returns(T.nilable(String)) }
       attr_accessor :card_network
 
-      # The type of card DEBIT or CREDIT
+      # The type of card, in lowercase: `credit`, `debit` or `prepaid`. Older payments
+      # can carry other casing.
       sig { returns(T.nilable(String)) }
       attr_accessor :card_type
 
+      # The type of subscription charge that this payment is for. Refer to `ChargeType`.
+      # The value is set for each payment status, not only for `succeeded`. The value is
+      # null when this payment charges no subscription.
+      sig { returns(T.nilable(Dodopayments::ChargeType::TaggedSymbol)) }
+      attr_accessor :charge_type
+
       # If payment is made using a checkout session, this field is set to the id of the
       # session.
       sig { returns(T.nilable(String)) }
@@ -157,7 +194,9 @@ module Dodopayments
       sig { returns(T.nilable(String)) }
       attr_accessor :invoice_id
 
-      # URL to download the invoice PDF for this payment.
+      # DEPRECATED: Use `GET /invoices/payments/{payment_id}` with an API key. URL to
+      # download the invoice PDF for this payment. The URL has no signed token. If the
+      # business asks for a credential on its invoice links, the URL needs an API key.
       sig { returns(T.nilable(String)) }
       attr_accessor :invoice_url
 
@@ -223,6 +262,7 @@ module Dodopayments
           customer: Dodopayments::CustomerLimitedDetails::OrHash,
           digital_products_delivered: T::Boolean,
           disputes: T::Array[Dodopayments::Dispute::OrHash],
+          includes_usage: T::Boolean,
           is_multi_subscription: T::Boolean,
           is_update_payment_method: T::Boolean,
           metadata: T::Hash[Symbol, Dodopayments::MetadataItem::Variants],
@@ -230,15 +270,20 @@ module Dodopayments
           payment_provider: Dodopayments::Payment::PaymentProvider::OrSymbol,
           refunds: T::Array[Dodopayments::RefundListItem::OrHash],
           retry_attempt: Integer,
+          service_periods:
+            T::Array[Dodopayments::SubscriptionServicePeriod::OrHash],
           settlement_amount: Integer,
           settlement_currency: Dodopayments::Currency::OrSymbol,
           subscription_ids: T::Array[String],
           total_amount: Integer,
+          card_exp_month: T.nilable(String),
+          card_exp_year: T.nilable(String),
           card_holder_name: T.nilable(String),
           card_issuing_country: T.nilable(Dodopayments::CountryCode::OrSymbol),
           card_last_four: T.nilable(String),
           card_network: T.nilable(String),
           card_type: T.nilable(String),
+          charge_type: T.nilable(Dodopayments::ChargeType::OrSymbol),
           checkout_session_id: T.nilable(String),
           custom_field_responses:
             T.nilable(T::Array[Dodopayments::CustomFieldResponse::OrHash]),
@@ -279,6 +324,10 @@ module Dodopayments
         digital_products_delivered:,
         # List of disputes associated with this payment
         disputes:,
+        # True when this payment also bills metered usage or credit overage. The usage is
+        # for the billing cycle before the service period, not for the service period. The
+        # value is set for each payment status. It is false when `charge_type` is null.
+        includes_usage:,
         # True when one payment starts more than one subscription. Read this field to find
         # the payment type. Do not read the length of `subscription_ids`. Do not read
         # `subscription_id` for null.
@@ -299,6 +348,15 @@ module Dodopayments
         # payment, `1`+ for each scheduled off-session retry after a failed renewal.
         # Always `0` for non-subscription payments.
         retry_attempt:,
+        # The service period of each subscription that this payment pays for. The order is
+        # the same as `subscription_ids`. For a plan change charge, the period starts at
+        # the plan change and ends at the next billing date. The list is empty unless the
+        # payment status is `succeeded`. The list is also empty for a one-time payment, an
+        # on-demand charge, or a payment method update. The list is set for `new`,
+        # `renewal` and `plan_change` charges that succeeded. It can be empty for some
+        # zero-amount payments. A `renewal` with no entry for its subscription bills usage
+        # only. That payment does not extend the service period.
+        service_periods:,
         # The amount that will be credited to your Dodo balance after currency conversion
         # and processing. Especially relevant for adaptive pricing where the customer's
         # payment currency differs from your settlement currency.
@@ -315,16 +373,30 @@ module Dodopayments
         # unit (e.g. cents for USD, yen for JPY, fils for KWD — see the currency's decimal
         # places)
         total_amount:,
+        # Expiry month of the card, as two digits from `01` to `12`. For Apple Pay and
+        # Google Pay, this is the expiry of the wallet token, which can differ from the
+        # expiry of the physical card.
+        card_exp_month: nil,
+        # Expiry year of the card, as four digits, for example `2029`. For Apple Pay and
+        # Google Pay, this is the expiry of the wallet token, which can differ from the
+        # expiry of the physical card.
+        card_exp_year: nil,
         # Cardholder name
         card_holder_name: nil,
         # ISO2 country code of the card
         card_issuing_country: nil,
         # The last four digits of the card
         card_last_four: nil,
-        # Card network like VISA, MASTERCARD etc.
+        # Card network, in lowercase, for example `visa`, `mastercard` or `amex`. Older
+        # payments can carry other casing.
         card_network: nil,
-        # The type of card DEBIT or CREDIT
+        # The type of card, in lowercase: `credit`, `debit` or `prepaid`. Older payments
+        # can carry other casing.
         card_type: nil,
+        # The type of subscription charge that this payment is for. Refer to `ChargeType`.
+        # The value is set for each payment status, not only for `succeeded`. The value is
+        # null when this payment charges no subscription.
+        charge_type: nil,
         # If payment is made using a checkout session, this field is set to the id of the
         # session.
         checkout_session_id: nil,
@@ -342,7 +414,9 @@ module Dodopayments
         error_message: nil,
         # Invoice ID for this payment. Uses India-specific invoice ID if available.
         invoice_id: nil,
-        # URL to download the invoice PDF for this payment.
+        # DEPRECATED: Use `GET /invoices/payments/{payment_id}` with an API key. URL to
+        # download the invoice PDF for this payment. The URL has no signed token. If the
+        # business asks for a credential on its invoice links, the URL needs an API key.
         invoice_url: nil,
         # Checkout URL
         payment_link: nil,
@@ -386,6 +460,7 @@ module Dodopayments
             customer: Dodopayments::CustomerLimitedDetails,
             digital_products_delivered: T::Boolean,
             disputes: T::Array[Dodopayments::Dispute],
+            includes_usage: T::Boolean,
             is_multi_subscription: T::Boolean,
             is_update_payment_method: T::Boolean,
             metadata: T::Hash[Symbol, Dodopayments::MetadataItem::Variants],
@@ -394,16 +469,20 @@ module Dodopayments
               Dodopayments::Payment::PaymentProvider::TaggedSymbol,
             refunds: T::Array[Dodopayments::RefundListItem],
             retry_attempt: Integer,
+            service_periods: T::Array[Dodopayments::SubscriptionServicePeriod],
             settlement_amount: Integer,
             settlement_currency: Dodopayments::Currency::TaggedSymbol,
             subscription_ids: T::Array[String],
             total_amount: Integer,
+            card_exp_month: T.nilable(String),
+            card_exp_year: T.nilable(String),
             card_holder_name: T.nilable(String),
             card_issuing_country:
               T.nilable(Dodopayments::CountryCode::TaggedSymbol),
             card_last_four: T.nilable(String),
             card_network: T.nilable(String),
             card_type: T.nilable(String),
+            charge_type: T.nilable(Dodopayments::ChargeType::TaggedSymbol),
             checkout_session_id: T.nilable(String),
             custom_field_responses:
               T.nilable(T::Array[Dodopayments::CustomFieldResponse]),

data/rbi/dodopayments/models/payment_list_response.rbi

@@ -34,6 +34,12 @@ module Dodopayments
       sig { returns(T::Boolean) }
       attr_accessor :has_license_key
 
+      # True when this payment also bills metered usage or credit overage. The usage is
+      # for the billing cycle before the service period, not for the service period. The
+      # value is set for each payment status. It is false when `charge_type` is null.
+      sig { returns(T::Boolean) }
+      attr_accessor :includes_usage
+
       # True when one payment starts more than one subscription. Read this field to find
       # the payment type. Do not read the length of `subscription_ids`. Do not read
       # `subscription_id` for null.
@@ -56,6 +62,23 @@ module Dodopayments
       end
       attr_accessor :payment_provider
 
+      # The retry attempt number of this payment. The value is `0` for the original
+      # payment. Each retry after a failed subscription renewal adds `1`. The value is
+      # always `0` for a payment that is not for a subscription.
+      sig { returns(Integer) }
+      attr_accessor :retry_attempt
+
+      # The service period of each subscription that this payment pays for. The order is
+      # the same as `subscription_ids`. For a plan change charge, the period starts at
+      # the plan change and ends at the next billing date. The list is empty unless the
+      # payment status is `succeeded`. The list is also empty for a one-time payment, an
+      # on-demand charge, or a payment method update. The list is set for `new`,
+      # `renewal` and `plan_change` charges that succeeded. It can be empty for some
+      # zero-amount payments. A `renewal` with no entry for its subscription bills usage
+      # only. That payment does not extend the service period.
+      sig { returns(T::Array[Dodopayments::SubscriptionServicePeriod]) }
+      attr_accessor :service_periods
+
       # Every subscription that this payment starts or charges, in a stable order. It is
       # empty for a one-time payment. It holds the value of `subscription_id` when the
       # payment names one subscription.
@@ -65,14 +88,43 @@ module Dodopayments
       sig { returns(Integer) }
       attr_accessor :total_amount
 
+      # Expiry month of the card, as two digits from `01` to `12`. For Apple Pay and
+      # Google Pay, this is the expiry of the wallet token, which can differ from the
+      # expiry of the physical card.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :card_exp_month
+
+      # Expiry year of the card, as four digits, for example `2029`. For Apple Pay and
+      # Google Pay, this is the expiry of the wallet token, which can differ from the
+      # expiry of the physical card.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :card_exp_year
+
       # The last four digits of the card
       sig { returns(T.nilable(String)) }
       attr_accessor :card_last_four
 
-      # Card network like VISA, MASTERCARD etc.
+      # Card network, in lowercase, for example `visa`, `mastercard` or `amex`. Older
+      # payments can carry other casing.
       sig { returns(T.nilable(String)) }
       attr_accessor :card_network
 
+      # The type of card, in lowercase: `credit`, `debit` or `prepaid`. Older payments
+      # can carry other casing.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :card_type
+
+      # The type of subscription charge that this payment is for. Refer to `ChargeType`.
+      # The value is set for each payment status, not only for `succeeded`. The value is
+      # null when this payment charges no subscription.
+      sig { returns(T.nilable(Dodopayments::ChargeType::TaggedSymbol)) }
+      attr_accessor :charge_type
+
+      # The ID of the checkout session for this payment. The value is null when the
+      # payment does not use a checkout session.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :checkout_session_id
+
       # The most recent dispute status for this payment. None if no disputes exist.
       sig { returns(T.nilable(Dodopayments::DisputeStatus::TaggedSymbol)) }
       attr_accessor :dispute_status
@@ -81,7 +133,9 @@ module Dodopayments
       sig { returns(T.nilable(String)) }
       attr_accessor :invoice_id
 
-      # URL to download the invoice PDF for this payment.
+      # DEPRECATED: Use `GET /invoices/payments/{payment_id}` with an API key. URL to
+      # download the invoice PDF for this payment. The URL has no signed token. If the
+      # business asks for a credential on its invoice links, the URL needs an API key.
       sig { returns(T.nilable(String)) }
       attr_accessor :invoice_url
 
@@ -112,15 +166,24 @@ module Dodopayments
           customer: Dodopayments::CustomerLimitedDetails::OrHash,
           digital_products_delivered: T::Boolean,
           has_license_key: T::Boolean,
+          includes_usage: T::Boolean,
           is_multi_subscription: T::Boolean,
           metadata: T::Hash[Symbol, Dodopayments::MetadataItem::Variants],
           payment_id: String,
           payment_provider:
             Dodopayments::Models::PaymentListResponse::PaymentProvider::OrSymbol,
+          retry_attempt: Integer,
+          service_periods:
+            T::Array[Dodopayments::SubscriptionServicePeriod::OrHash],
           subscription_ids: T::Array[String],
           total_amount: Integer,
+          card_exp_month: T.nilable(String),
+          card_exp_year: T.nilable(String),
           card_last_four: T.nilable(String),
           card_network: T.nilable(String),
+          card_type: T.nilable(String),
+          charge_type: T.nilable(Dodopayments::ChargeType::OrSymbol),
+          checkout_session_id: T.nilable(String),
           dispute_status: T.nilable(Dodopayments::DisputeStatus::OrSymbol),
           invoice_id: T.nilable(String),
           invoice_url: T.nilable(String),
@@ -138,6 +201,10 @@ module Dodopayments
         customer:,
         digital_products_delivered:,
         has_license_key:,
+        # True when this payment also bills metered usage or credit overage. The usage is
+        # for the billing cycle before the service period, not for the service period. The
+        # value is set for each payment status. It is false when `charge_type` is null.
+        includes_usage:,
         # True when one payment starts more than one subscription. Read this field to find
         # the payment type. Do not read the length of `subscription_ids`. Do not read
         # `subscription_id` for null.
@@ -148,20 +215,54 @@ module Dodopayments
         # Which processor handled this payment. `stripe` / `adyen` for BYOP routes (the
         # merchant's own payment connector); `dodo` for everything Dodo processed itself.
         payment_provider:,
+        # The retry attempt number of this payment. The value is `0` for the original
+        # payment. Each retry after a failed subscription renewal adds `1`. The value is
+        # always `0` for a payment that is not for a subscription.
+        retry_attempt:,
+        # The service period of each subscription that this payment pays for. The order is
+        # the same as `subscription_ids`. For a plan change charge, the period starts at
+        # the plan change and ends at the next billing date. The list is empty unless the
+        # payment status is `succeeded`. The list is also empty for a one-time payment, an
+        # on-demand charge, or a payment method update. The list is set for `new`,
+        # `renewal` and `plan_change` charges that succeeded. It can be empty for some
+        # zero-amount payments. A `renewal` with no entry for its subscription bills usage
+        # only. That payment does not extend the service period.
+        service_periods:,
         # Every subscription that this payment starts or charges, in a stable order. It is
         # empty for a one-time payment. It holds the value of `subscription_id` when the
         # payment names one subscription.
         subscription_ids:,
         total_amount:,
+        # Expiry month of the card, as two digits from `01` to `12`. For Apple Pay and
+        # Google Pay, this is the expiry of the wallet token, which can differ from the
+        # expiry of the physical card.
+        card_exp_month: nil,
+        # Expiry year of the card, as four digits, for example `2029`. For Apple Pay and
+        # Google Pay, this is the expiry of the wallet token, which can differ from the
+        # expiry of the physical card.
+        card_exp_year: nil,
         # The last four digits of the card
         card_last_four: nil,
-        # Card network like VISA, MASTERCARD etc.
+        # Card network, in lowercase, for example `visa`, `mastercard` or `amex`. Older
+        # payments can carry other casing.
         card_network: nil,
+        # The type of card, in lowercase: `credit`, `debit` or `prepaid`. Older payments
+        # can carry other casing.
+        card_type: nil,
+        # The type of subscription charge that this payment is for. Refer to `ChargeType`.
+        # The value is set for each payment status, not only for `succeeded`. The value is
+        # null when this payment charges no subscription.
+        charge_type: nil,
+        # The ID of the checkout session for this payment. The value is null when the
+        # payment does not use a checkout session.
+        checkout_session_id: nil,
         # The most recent dispute status for this payment. None if no disputes exist.
         dispute_status: nil,
         # Invoice ID for this payment. Uses India-specific invoice ID if available.
         invoice_id: nil,
-        # URL to download the invoice PDF for this payment.
+        # DEPRECATED: Use `GET /invoices/payments/{payment_id}` with an API key. URL to
+        # download the invoice PDF for this payment. The URL has no signed token. If the
+        # business asks for a credential on its invoice links, the URL needs an API key.
         invoice_url: nil,
         payment_method: nil,
         payment_method_type: nil,
@@ -182,15 +283,23 @@ module Dodopayments
             customer: Dodopayments::CustomerLimitedDetails,
             digital_products_delivered: T::Boolean,
             has_license_key: T::Boolean,
+            includes_usage: T::Boolean,
             is_multi_subscription: T::Boolean,
             metadata: T::Hash[Symbol, Dodopayments::MetadataItem::Variants],
             payment_id: String,
             payment_provider:
               Dodopayments::Models::PaymentListResponse::PaymentProvider::TaggedSymbol,
+            retry_attempt: Integer,
+            service_periods: T::Array[Dodopayments::SubscriptionServicePeriod],
             subscription_ids: T::Array[String],
             total_amount: Integer,
+            card_exp_month: T.nilable(String),
+            card_exp_year: T.nilable(String),
             card_last_four: T.nilable(String),
             card_network: T.nilable(String),
+            card_type: T.nilable(String),
+            charge_type: T.nilable(Dodopayments::ChargeType::TaggedSymbol),
+            checkout_session_id: T.nilable(String),
             dispute_status:
               T.nilable(Dodopayments::DisputeStatus::TaggedSymbol),
             invoice_id: T.nilable(String),

data/rbi/dodopayments/models/price.rbi

@@ -167,12 +167,14 @@ module Dodopayments
         sig { returns(Dodopayments::Currency::OrSymbol) }
         attr_accessor :currency
 
-        # Number of units for the payment frequency. For example, a value of `1` with a
-        # `payment_frequency_interval` of `month` represents monthly payments.
+        # Number of `payment_frequency_interval` units between two charges. This field
+        # sets the billing cycle. For example, `1` with a `payment_frequency_interval` of
+        # `month` charges the customer every month.
         sig { returns(Integer) }
         attr_accessor :payment_frequency_count
 
-        # The time interval for the payment frequency (e.g., day, month, year).
+        # The time unit of the billing cycle (e.g., day, month, year). Use it with
+        # `payment_frequency_count`.
         sig { returns(Dodopayments::TimeInterval::OrSymbol) }
         attr_accessor :payment_frequency_interval
 
@@ -181,12 +183,28 @@ module Dodopayments
         sig { returns(Integer) }
         attr_accessor :price
 
-        # Number of units for the subscription period. For example, a value of `12` with a
-        # `subscription_period_interval` of `month` represents a one-year subscription.
+        # Number of `subscription_period_interval` units for the total duration of the
+        # subscription. This field does not set the billing cycle. Use
+        # `payment_frequency_count` for the billing cycle. When this period ends, the
+        # subscription expires. Dodo Payments does not start a new billing cycle after the
+        # subscription expires. Dodo Payments can still retry a failed payment for an
+        # earlier billing cycle.
+        #
+        # For a subscription that renews until the customer cancels it, set this to `20`
+        # with a `subscription_period_interval` of `year`. This is the recommended value
+        # and also the maximum. The subscription expires after 20 years if the customer
+        # does not cancel it before then.
+        #
+        # For example, a monthly plan uses a `payment_frequency_count` of `1`, a
+        # `payment_frequency_interval` of `month`, and a subscription period of `20`
+        # `year`. Do not set the subscription period to `1` `month` for a monthly plan:
+        # the subscription then expires after one month.
         sig { returns(Integer) }
         attr_accessor :subscription_period_count
 
-        # The time interval for the subscription period (e.g., day, month, year).
+        # The time unit of the total subscription duration (e.g., day, month, year). Use
+        # it with `subscription_period_count`. The recommended value is `year`, with a
+        # `subscription_period_count` of `20`.
         sig { returns(Dodopayments::TimeInterval::OrSymbol) }
         attr_accessor :subscription_period_interval
 
@@ -280,18 +298,36 @@ module Dodopayments
         def self.new(
           # The currency in which the payment is made.
           currency:,
-          # Number of units for the payment frequency. For example, a value of `1` with a
-          # `payment_frequency_interval` of `month` represents monthly payments.
+          # Number of `payment_frequency_interval` units between two charges. This field
+          # sets the billing cycle. For example, `1` with a `payment_frequency_interval` of
+          # `month` charges the customer every month.
           payment_frequency_count:,
-          # The time interval for the payment frequency (e.g., day, month, year).
+          # The time unit of the billing cycle (e.g., day, month, year). Use it with
+          # `payment_frequency_count`.
           payment_frequency_interval:,
           # The payment amount. Represented in the lowest denomination of the currency
           # (e.g., cents for USD). For example, to charge $1.00, pass `100`.
           price:,
-          # Number of units for the subscription period. For example, a value of `12` with a
-          # `subscription_period_interval` of `month` represents a one-year subscription.
+          # Number of `subscription_period_interval` units for the total duration of the
+          # subscription. This field does not set the billing cycle. Use
+          # `payment_frequency_count` for the billing cycle. When this period ends, the
+          # subscription expires. Dodo Payments does not start a new billing cycle after the
+          # subscription expires. Dodo Payments can still retry a failed payment for an
+          # earlier billing cycle.
+          #
+          # For a subscription that renews until the customer cancels it, set this to `20`
+          # with a `subscription_period_interval` of `year`. This is the recommended value
+          # and also the maximum. The subscription expires after 20 years if the customer
+          # does not cancel it before then.
+          #
+          # For example, a monthly plan uses a `payment_frequency_count` of `1`, a
+          # `payment_frequency_interval` of `month`, and a subscription period of `20`
+          # `year`. Do not set the subscription period to `1` `month` for a monthly plan:
+          # the subscription then expires after one month.
           subscription_period_count:,
-          # The time interval for the subscription period (e.g., day, month, year).
+          # The time unit of the total subscription duration (e.g., day, month, year). Use
+          # it with `subscription_period_count`. The recommended value is `year`, with a
+          # `subscription_period_count` of `20`.
           subscription_period_interval:,
           # Deprecated: use `discount_bps` instead.
           #
@@ -372,21 +408,39 @@ module Dodopayments
         sig { returns(Integer) }
         attr_accessor :fixed_price
 
-        # Number of units for the payment frequency. For example, a value of `1` with a
-        # `payment_frequency_interval` of `month` represents monthly payments.
+        # Number of `payment_frequency_interval` units between two charges. This field
+        # sets the billing cycle. For example, `1` with a `payment_frequency_interval` of
+        # `month` charges the customer every month.
         sig { returns(Integer) }
         attr_accessor :payment_frequency_count
 
-        # The time interval for the payment frequency (e.g., day, month, year).
+        # The time unit of the billing cycle (e.g., day, month, year). Use it with
+        # `payment_frequency_count`.
         sig { returns(Dodopayments::TimeInterval::OrSymbol) }
         attr_accessor :payment_frequency_interval
 
-        # Number of units for the subscription period. For example, a value of `12` with a
-        # `subscription_period_interval` of `month` represents a one-year subscription.
+        # Number of `subscription_period_interval` units for the total duration of the
+        # subscription. This field does not set the billing cycle. Use
+        # `payment_frequency_count` for the billing cycle. When this period ends, the
+        # subscription expires. Dodo Payments does not start a new billing cycle after the
+        # subscription expires. Dodo Payments can still retry a failed payment for an
+        # earlier billing cycle.
+        #
+        # For a subscription that renews until the customer cancels it, set this to `20`
+        # with a `subscription_period_interval` of `year`. This is the recommended value
+        # and also the maximum. The subscription expires after 20 years if the customer
+        # does not cancel it before then.
+        #
+        # For example, a monthly plan uses a `payment_frequency_count` of `1`, a
+        # `payment_frequency_interval` of `month`, and a subscription period of `20`
+        # `year`. Do not set the subscription period to `1` `month` for a monthly plan:
+        # the subscription then expires after one month.
         sig { returns(Integer) }
         attr_accessor :subscription_period_count
 
-        # The time interval for the subscription period (e.g., day, month, year).
+        # The time unit of the total subscription duration (e.g., day, month, year). Use
+        # it with `subscription_period_count`. The recommended value is `year`, with a
+        # `subscription_period_count` of `20`.
         sig { returns(Dodopayments::TimeInterval::OrSymbol) }
         attr_accessor :subscription_period_interval
 
@@ -451,15 +505,33 @@ module Dodopayments
           # The fixed payment amount. Represented in the lowest denomination of the currency
           # (e.g., cents for USD). For example, to charge $1.00, pass `100`.
           fixed_price:,
-          # Number of units for the payment frequency. For example, a value of `1` with a
-          # `payment_frequency_interval` of `month` represents monthly payments.
+          # Number of `payment_frequency_interval` units between two charges. This field
+          # sets the billing cycle. For example, `1` with a `payment_frequency_interval` of
+          # `month` charges the customer every month.
           payment_frequency_count:,
-          # The time interval for the payment frequency (e.g., day, month, year).
+          # The time unit of the billing cycle (e.g., day, month, year). Use it with
+          # `payment_frequency_count`.
           payment_frequency_interval:,
-          # Number of units for the subscription period. For example, a value of `12` with a
-          # `subscription_period_interval` of `month` represents a one-year subscription.
+          # Number of `subscription_period_interval` units for the total duration of the
+          # subscription. This field does not set the billing cycle. Use
+          # `payment_frequency_count` for the billing cycle. When this period ends, the
+          # subscription expires. Dodo Payments does not start a new billing cycle after the
+          # subscription expires. Dodo Payments can still retry a failed payment for an
+          # earlier billing cycle.
+          #
+          # For a subscription that renews until the customer cancels it, set this to `20`
+          # with a `subscription_period_interval` of `year`. This is the recommended value
+          # and also the maximum. The subscription expires after 20 years if the customer
+          # does not cancel it before then.
+          #
+          # For example, a monthly plan uses a `payment_frequency_count` of `1`, a
+          # `payment_frequency_interval` of `month`, and a subscription period of `20`
+          # `year`. Do not set the subscription period to `1` `month` for a monthly plan:
+          # the subscription then expires after one month.
           subscription_period_count:,
-          # The time interval for the subscription period (e.g., day, month, year).
+          # The time unit of the total subscription duration (e.g., day, month, year). Use
+          # it with `subscription_period_count`. The recommended value is `year`, with a
+          # `subscription_period_count` of `20`.
           subscription_period_interval:,
           # Deprecated: use `discount_bps` instead.
           #

data/rbi/dodopayments/models/product_collection.rbi

@@ -350,6 +350,11 @@ module Dodopayments
             :do_not_bill,
             Dodopayments::ProductCollection::ProrationBillingModeOnDowngrade::TaggedSymbol
           )
+        PRORATED_IMMEDIATELY_KEEP_CYCLE =
+          T.let(
+            :prorated_immediately_keep_cycle,
+            Dodopayments::ProductCollection::ProrationBillingModeOnDowngrade::TaggedSymbol
+          )
 
         sig do
           override.returns(
@@ -396,6 +401,11 @@ module Dodopayments
             :do_not_bill,
             Dodopayments::ProductCollection::ProrationBillingModeOnUpgrade::TaggedSymbol
           )
+        PRORATED_IMMEDIATELY_KEEP_CYCLE =
+          T.let(
+            :prorated_immediately_keep_cycle,
+            Dodopayments::ProductCollection::ProrationBillingModeOnUpgrade::TaggedSymbol
+          )
 
         sig do
           override.returns(

data/rbi/dodopayments/models/product_collection_create_params.rbi

@@ -330,6 +330,11 @@ module Dodopayments
             :do_not_bill,
             Dodopayments::ProductCollectionCreateParams::ProrationBillingModeOnDowngrade::TaggedSymbol
           )
+        PRORATED_IMMEDIATELY_KEEP_CYCLE =
+          T.let(
+            :prorated_immediately_keep_cycle,
+            Dodopayments::ProductCollectionCreateParams::ProrationBillingModeOnDowngrade::TaggedSymbol
+          )
 
         sig do
           override.returns(
@@ -376,6 +381,11 @@ module Dodopayments
             :do_not_bill,
             Dodopayments::ProductCollectionCreateParams::ProrationBillingModeOnUpgrade::TaggedSymbol
           )
+        PRORATED_IMMEDIATELY_KEEP_CYCLE =
+          T.let(
+            :prorated_immediately_keep_cycle,
+            Dodopayments::ProductCollectionCreateParams::ProrationBillingModeOnUpgrade::TaggedSymbol
+          )
 
         sig do
           override.returns(