dodopayments 2.20.1 → 2.21.0

data/rbi/dodopayments/models/checkout_session_preview_response.rbi

@@ -99,6 +99,17 @@ module Dodopayments
       sig { returns(T.nilable(Integer)) }
       attr_accessor :total_tax
 
+      # Per-unit trial amount after discounts, in the price currency's minor units
+      # (pre-quantity, pre-tax; see `current_breakup` for the taxed total due today).
+      # Only present for a paid trial; `None` for a free trial or no trial.
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :trial_amount
+
+      # Effective trial duration in days for the subscription line, when there's a trial
+      # (free or paid). `None` if no subscription or no trial.
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :trial_period_days
+
       # Data returned by the calculate checkout session API
       sig do
         params(
@@ -120,7 +131,9 @@ module Dodopayments
           tax_id_business_name: T.nilable(String),
           tax_id_err_msg: T.nilable(String),
           tax_id_format_name: T.nilable(String),
-          total_tax: T.nilable(Integer)
+          total_tax: T.nilable(Integer),
+          trial_amount: T.nilable(Integer),
+          trial_period_days: T.nilable(Integer)
         ).returns(T.attached_class)
       end
       def self.new(
@@ -153,7 +166,14 @@ module Dodopayments
         # The matched tax ID notation (e.g. "VAT Number", "GSTIN") when valid
         tax_id_format_name: nil,
         # Total tax
-        total_tax: nil
+        total_tax: nil,
+        # Per-unit trial amount after discounts, in the price currency's minor units
+        # (pre-quantity, pre-tax; see `current_breakup` for the taxed total due today).
+        # Only present for a paid trial; `None` for a free trial or no trial.
+        trial_amount: nil,
+        # Effective trial duration in days for the subscription line, when there's a trial
+        # (free or paid). `None` if no subscription or no trial.
+        trial_period_days: nil
       )
       end
 
@@ -178,7 +198,9 @@ module Dodopayments
             tax_id_business_name: T.nilable(String),
             tax_id_err_msg: T.nilable(String),
             tax_id_format_name: T.nilable(String),
-            total_tax: T.nilable(Integer)
+            total_tax: T.nilable(Integer),
+            trial_amount: T.nilable(Integer),
+            trial_period_days: T.nilable(Integer)
           }
         )
       end
@@ -330,7 +352,8 @@ module Dodopayments
         sig { returns(T.nilable(String)) }
         attr_accessor :description
 
-        # discount percentage
+        # Percentage rate (basis points) of the applicable percentage code; null for flat
+        # codes (their deduction is `og_price - discounted_price`).
         sig { returns(T.nilable(Integer)) }
         attr_accessor :discount_amount
 
@@ -407,7 +430,8 @@ module Dodopayments
           tax_rate:,
           addons: nil,
           description: nil,
-          # discount percentage
+          # Percentage rate (basis points) of the applicable percentage code; null for flat
+          # codes (their deduction is `og_price - discounted_price`).
           discount_amount: nil,
           # number of cycles the discount will apply
           discount_cycle: nil,
@@ -619,6 +643,8 @@ module Dodopayments
           sig { returns(T.nilable(String)) }
           attr_accessor :description
 
+          # Percentage rate (basis points) of the applicable percentage code; null for flat
+          # codes (their deduction is `og_price - discounted_price`).
           sig { returns(T.nilable(Integer)) }
           attr_accessor :discount_amount
 
@@ -656,6 +682,8 @@ module Dodopayments
             tax_inclusive:,
             tax_rate:,
             description: nil,
+            # Percentage rate (basis points) of the applicable percentage code; null for flat
+            # codes (their deduction is `og_price - discounted_price`).
             discount_amount: nil,
             tax: nil
           )

data/rbi/dodopayments/models/credit_entitlements/balance_create_ledger_entry_params.rbi

@@ -21,7 +21,9 @@ module Dodopayments
         sig { returns(String) }
         attr_accessor :customer_id
 
-        # Amount to credit or debit
+        # Amount to credit or debit. Bounded to a `NUMERIC(38,28)` column, so the integer
+        # part must have fewer than 10 digits (< 10^10); larger values previously reached
+        # the DB and failed with a 22003 overflow surfaced as a 500.
         sig { returns(String) }
         attr_accessor :amount
 
@@ -70,7 +72,9 @@ module Dodopayments
         def self.new(
           credit_entitlement_id:,
           customer_id:,
-          # Amount to credit or debit
+          # Amount to credit or debit. Bounded to a `NUMERIC(38,28)` column, so the integer
+          # part must have fewer than 10 digits (< 10^10); larger values previously reached
+          # the DB and failed with a 22003 overflow surfaced as a 500.
           amount:,
           # Entry type: credit or debit
           entry_type:,

data/rbi/dodopayments/models/discount.rbi

@@ -24,6 +24,10 @@ module Dodopayments
       sig { returns(Time) }
       attr_accessor :created_at
 
+      # Who may redeem this discount code.
+      sig { returns(Dodopayments::Discount::CustomerEligibility::TaggedSymbol) }
+      attr_accessor :customer_eligibility
+
       # The unique discount ID
       sig { returns(String) }
       attr_accessor :discount_id
@@ -45,10 +49,25 @@ module Dodopayments
       sig { returns(Integer) }
       attr_accessor :times_used
 
-      # The type of discount. Currently only `percentage` is supported.
+      # The type of discount (`percentage` or `flat`).
       sig { returns(Dodopayments::DiscountType::TaggedSymbol) }
       attr_accessor :type
 
+      # Per-currency options (flat deduction / percentage cap + minimum subtotal). Empty
+      # for discounts without any configured currency options.
+      sig do
+        returns(T.nilable(T::Array[Dodopayments::Discount::CurrencyOption]))
+      end
+      attr_reader :currency_options
+
+      sig do
+        params(
+          currency_options:
+            T::Array[Dodopayments::Discount::CurrencyOption::OrHash]
+        ).void
+      end
+      attr_writer :currency_options
+
       # Optional date/time after which discount is expired.
       sig { returns(T.nilable(Time)) }
       attr_accessor :expires_at
@@ -57,6 +76,15 @@ module Dodopayments
       sig { returns(T.nilable(String)) }
       attr_accessor :name
 
+      # Maximum number of times a single customer may redeem this discount, if any.
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :per_customer_usage_limit
+
+      # Optional date/time before which the discount is not yet active. NULL = active
+      # immediately.
+      sig { returns(T.nilable(Time)) }
+      attr_accessor :starts_at
+
       # Number of subscription billing cycles this discount is valid for. If not
       # provided, the discount will be applied indefinitely to all recurring payments
       # related to the subscription.
@@ -73,14 +101,20 @@ module Dodopayments
           business_id: String,
           code: String,
           created_at: Time,
+          customer_eligibility:
+            Dodopayments::Discount::CustomerEligibility::OrSymbol,
           discount_id: String,
           metadata: T::Hash[Symbol, Dodopayments::MetadataItem::Variants],
           preserve_on_plan_change: T::Boolean,
           restricted_to: T::Array[String],
           times_used: Integer,
           type: Dodopayments::DiscountType::OrSymbol,
+          currency_options:
+            T::Array[Dodopayments::Discount::CurrencyOption::OrHash],
           expires_at: T.nilable(Time),
           name: T.nilable(String),
+          per_customer_usage_limit: T.nilable(Integer),
+          starts_at: T.nilable(Time),
           subscription_cycles: T.nilable(Integer),
           usage_limit: T.nilable(Integer)
         ).returns(T.attached_class)
@@ -94,6 +128,8 @@ module Dodopayments
         code:,
         # Timestamp when the discount is created
         created_at:,
+        # Who may redeem this discount code.
+        customer_eligibility:,
         # The unique discount ID
         discount_id:,
         # Arbitrary key-value metadata. Values can be string, integer, number, or boolean.
@@ -105,12 +141,20 @@ module Dodopayments
         restricted_to:,
         # How many times this discount has been used.
         times_used:,
-        # The type of discount. Currently only `percentage` is supported.
+        # The type of discount (`percentage` or `flat`).
         type:,
+        # Per-currency options (flat deduction / percentage cap + minimum subtotal). Empty
+        # for discounts without any configured currency options.
+        currency_options: nil,
         # Optional date/time after which discount is expired.
         expires_at: nil,
         # Name for the Discount
         name: nil,
+        # Maximum number of times a single customer may redeem this discount, if any.
+        per_customer_usage_limit: nil,
+        # Optional date/time before which the discount is not yet active. NULL = active
+        # immediately.
+        starts_at: nil,
         # Number of subscription billing cycles this discount is valid for. If not
         # provided, the discount will be applied indefinitely to all recurring payments
         # related to the subscription.
@@ -127,14 +171,19 @@ module Dodopayments
             business_id: String,
             code: String,
             created_at: Time,
+            customer_eligibility:
+              Dodopayments::Discount::CustomerEligibility::TaggedSymbol,
             discount_id: String,
             metadata: T::Hash[Symbol, Dodopayments::MetadataItem::Variants],
             preserve_on_plan_change: T::Boolean,
             restricted_to: T::Array[String],
             times_used: Integer,
             type: Dodopayments::DiscountType::TaggedSymbol,
+            currency_options: T::Array[Dodopayments::Discount::CurrencyOption],
             expires_at: T.nilable(Time),
             name: T.nilable(String),
+            per_customer_usage_limit: T.nilable(Integer),
+            starts_at: T.nilable(Time),
             subscription_cycles: T.nilable(Integer),
             usage_limit: T.nilable(Integer)
           }
@@ -142,6 +191,106 @@ module Dodopayments
       end
       def to_hash
       end
+
+      # Who may redeem this discount code.
+      module CustomerEligibility
+        extend Dodopayments::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(Symbol, Dodopayments::Discount::CustomerEligibility)
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        ANY =
+          T.let(:any, Dodopayments::Discount::CustomerEligibility::TaggedSymbol)
+        FIRST_TIME =
+          T.let(
+            :first_time,
+            Dodopayments::Discount::CustomerEligibility::TaggedSymbol
+          )
+        EXISTING =
+          T.let(
+            :existing,
+            Dodopayments::Discount::CustomerEligibility::TaggedSymbol
+          )
+        SPECIFIC =
+          T.let(
+            :specific,
+            Dodopayments::Discount::CustomerEligibility::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[Dodopayments::Discount::CustomerEligibility::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+
+      class CurrencyOption < Dodopayments::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Dodopayments::Discount::CurrencyOption,
+              Dodopayments::Internal::AnyHash
+            )
+          end
+
+        # The currency this option applies to.
+        sig { returns(Dodopayments::Currency::TaggedSymbol) }
+        attr_accessor :currency
+
+        # Whether this is the default row FX conversions pivot from.
+        sig { returns(T::Boolean) }
+        attr_accessor :is_default
+
+        # Eligible-cart threshold in this currency's subunits (0 = no minimum).
+        sig { returns(Integer) }
+        attr_accessor :minimum_subtotal
+
+        # The most this code discounts in this currency's subunits (flat deduction or
+        # percentage cap).
+        sig { returns(T.nilable(Integer)) }
+        attr_accessor :max_amount_possible
+
+        # A per-currency discount option (response shape). `max_amount_possible` mirrors
+        # the DB column of the same name.
+        sig do
+          params(
+            currency: Dodopayments::Currency::OrSymbol,
+            is_default: T::Boolean,
+            minimum_subtotal: Integer,
+            max_amount_possible: T.nilable(Integer)
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The currency this option applies to.
+          currency:,
+          # Whether this is the default row FX conversions pivot from.
+          is_default:,
+          # Eligible-cart threshold in this currency's subunits (0 = no minimum).
+          minimum_subtotal:,
+          # The most this code discounts in this currency's subunits (flat deduction or
+          # percentage cap).
+          max_amount_possible: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              currency: Dodopayments::Currency::TaggedSymbol,
+              is_default: T::Boolean,
+              minimum_subtotal: Integer,
+              max_amount_possible: T.nilable(Integer)
+            }
+          )
+        end
+        def to_hash
+        end
+      end
     end
   end
 end

data/rbi/dodopayments/models/discount_create_params.rbi

@@ -21,7 +21,7 @@ module Dodopayments
       sig { returns(Integer) }
       attr_accessor :amount
 
-      # The discount type. Currently only `percentage` is supported.
+      # The discount type: `percentage` or `flat` (`flat_per_unit` stays blocked).
       sig { returns(Dodopayments::DiscountType::OrSymbol) }
       attr_accessor :type
 
@@ -32,6 +32,31 @@ module Dodopayments
       sig { returns(T.nilable(String)) }
       attr_accessor :code
 
+      # Per-currency options (flat deduction / percentage cap + minimum subtotal).
+      # Required for `flat` codes (must include a resolvable default); optional
+      # per-currency caps for `percentage` codes. Per-row invariants are checked in
+      # `normalize_currency_options`, not via `#[validate(nested)]`.
+      sig do
+        returns(
+          T.nilable(
+            T::Array[Dodopayments::DiscountCreateParams::CurrencyOption]
+          )
+        )
+      end
+      attr_accessor :currency_options
+
+      # Who may redeem this discount code. Defaults to `any` (unrestricted). `specific`
+      # starts with zero attached customers (fails closed) until customers are attached
+      # via `POST /discounts/{id}/customers`.
+      sig do
+        returns(
+          T.nilable(
+            Dodopayments::DiscountCreateParams::CustomerEligibility::OrSymbol
+          )
+        )
+      end
+      attr_accessor :customer_eligibility
+
       # When the discount expires, if ever.
       sig { returns(T.nilable(Time)) }
       attr_accessor :expires_at
@@ -54,6 +79,11 @@ module Dodopayments
       sig { returns(T.nilable(String)) }
       attr_accessor :name
 
+      # Maximum number of times a single customer may redeem this discount. Must be
+      # `<= usage_limit` when both are set.
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :per_customer_usage_limit
+
       # Whether this discount should be preserved when a subscription changes plans.
       # Default: false (discount is removed on plan change)
       sig { returns(T.nilable(T::Boolean)) }
@@ -66,6 +96,11 @@ module Dodopayments
       sig { returns(T.nilable(T::Array[String])) }
       attr_accessor :restricted_to
 
+      # When the discount becomes active, if scheduled for the future. NULL = active
+      # immediately. Must be strictly before `expires_at` when both are set.
+      sig { returns(T.nilable(Time)) }
+      attr_accessor :starts_at
+
       # Number of subscription billing cycles this discount is valid for. If not
       # provided, the discount will be applied indefinitely to all recurring payments
       # related to the subscription.
@@ -81,11 +116,23 @@ module Dodopayments
           amount: Integer,
           type: Dodopayments::DiscountType::OrSymbol,
           code: T.nilable(String),
+          currency_options:
+            T.nilable(
+              T::Array[
+                Dodopayments::DiscountCreateParams::CurrencyOption::OrHash
+              ]
+            ),
+          customer_eligibility:
+            T.nilable(
+              Dodopayments::DiscountCreateParams::CustomerEligibility::OrSymbol
+            ),
           expires_at: T.nilable(Time),
           metadata: T::Hash[Symbol, Dodopayments::MetadataItem::Variants],
           name: T.nilable(String),
+          per_customer_usage_limit: T.nilable(Integer),
           preserve_on_plan_change: T::Boolean,
           restricted_to: T.nilable(T::Array[String]),
+          starts_at: T.nilable(Time),
           subscription_cycles: T.nilable(Integer),
           usage_limit: T.nilable(Integer),
           request_options: Dodopayments::RequestOptions::OrHash
@@ -97,23 +144,38 @@ module Dodopayments
         #
         # Must be at least 1.
         amount:,
-        # The discount type. Currently only `percentage` is supported.
+        # The discount type: `percentage` or `flat` (`flat_per_unit` stays blocked).
         type:,
         # Optionally supply a code (will be uppercased).
         #
         # - Must be at least 3 characters if provided.
         # - If omitted, a random 16-character code is generated.
         code: nil,
+        # Per-currency options (flat deduction / percentage cap + minimum subtotal).
+        # Required for `flat` codes (must include a resolvable default); optional
+        # per-currency caps for `percentage` codes. Per-row invariants are checked in
+        # `normalize_currency_options`, not via `#[validate(nested)]`.
+        currency_options: nil,
+        # Who may redeem this discount code. Defaults to `any` (unrestricted). `specific`
+        # starts with zero attached customers (fails closed) until customers are attached
+        # via `POST /discounts/{id}/customers`.
+        customer_eligibility: nil,
         # When the discount expires, if ever.
         expires_at: nil,
         # Additional metadata for the discount
         metadata: nil,
         name: nil,
+        # Maximum number of times a single customer may redeem this discount. Must be
+        # `<= usage_limit` when both are set.
+        per_customer_usage_limit: nil,
         # Whether this discount should be preserved when a subscription changes plans.
         # Default: false (discount is removed on plan change)
         preserve_on_plan_change: nil,
         # List of product IDs to restrict usage (if any).
         restricted_to: nil,
+        # When the discount becomes active, if scheduled for the future. NULL = active
+        # immediately. Must be strictly before `expires_at` when both are set.
+        starts_at: nil,
         # Number of subscription billing cycles this discount is valid for. If not
         # provided, the discount will be applied indefinitely to all recurring payments
         # related to the subscription.
@@ -130,11 +192,21 @@ module Dodopayments
             amount: Integer,
             type: Dodopayments::DiscountType::OrSymbol,
             code: T.nilable(String),
+            currency_options:
+              T.nilable(
+                T::Array[Dodopayments::DiscountCreateParams::CurrencyOption]
+              ),
+            customer_eligibility:
+              T.nilable(
+                Dodopayments::DiscountCreateParams::CustomerEligibility::OrSymbol
+              ),
             expires_at: T.nilable(Time),
             metadata: T::Hash[Symbol, Dodopayments::MetadataItem::Variants],
             name: T.nilable(String),
+            per_customer_usage_limit: T.nilable(Integer),
             preserve_on_plan_change: T::Boolean,
             restricted_to: T.nilable(T::Array[String]),
+            starts_at: T.nilable(Time),
             subscription_cycles: T.nilable(Integer),
             usage_limit: T.nilable(Integer),
             request_options: Dodopayments::RequestOptions
@@ -143,6 +215,129 @@ module Dodopayments
       end
       def to_hash
       end
+
+      class CurrencyOption < Dodopayments::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Dodopayments::DiscountCreateParams::CurrencyOption,
+              Dodopayments::Internal::AnyHash
+            )
+          end
+
+        # The currency this option applies to.
+        sig { returns(Dodopayments::Currency::OrSymbol) }
+        attr_accessor :currency
+
+        # Whether this row is the default to convert from for unconfigured currencies. At
+        # most one row per discount may be default.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_reader :is_default
+
+        sig { params(is_default: T::Boolean).void }
+        attr_writer :is_default
+
+        # The most this code discounts in this currency's subunits. For `flat` codes this
+        # is the deduction; for `percentage` codes it is the max-discount cap. Must be > 0
+        # if provided.
+        sig { returns(T.nilable(Integer)) }
+        attr_accessor :max_amount_possible
+
+        # Eligible-cart threshold in this currency's subunits (0 = no minimum).
+        sig { returns(T.nilable(Integer)) }
+        attr_reader :minimum_subtotal
+
+        sig { params(minimum_subtotal: Integer).void }
+        attr_writer :minimum_subtotal
+
+        # A per-currency discount option (request shape).
+        #
+        # `max_amount_possible` is the most this code discounts in this currency — the
+        # flat deduction for `flat` codes, or the max-discount cap for `percentage` codes.
+        # Maps to the DB column of the same name.
+        sig do
+          params(
+            currency: Dodopayments::Currency::OrSymbol,
+            is_default: T::Boolean,
+            max_amount_possible: T.nilable(Integer),
+            minimum_subtotal: Integer
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The currency this option applies to.
+          currency:,
+          # Whether this row is the default to convert from for unconfigured currencies. At
+          # most one row per discount may be default.
+          is_default: nil,
+          # The most this code discounts in this currency's subunits. For `flat` codes this
+          # is the deduction; for `percentage` codes it is the max-discount cap. Must be > 0
+          # if provided.
+          max_amount_possible: nil,
+          # Eligible-cart threshold in this currency's subunits (0 = no minimum).
+          minimum_subtotal: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              currency: Dodopayments::Currency::OrSymbol,
+              is_default: T::Boolean,
+              max_amount_possible: T.nilable(Integer),
+              minimum_subtotal: Integer
+            }
+          )
+        end
+        def to_hash
+        end
+      end
+
+      # Who may redeem this discount code. Defaults to `any` (unrestricted). `specific`
+      # starts with zero attached customers (fails closed) until customers are attached
+      # via `POST /discounts/{id}/customers`.
+      module CustomerEligibility
+        extend Dodopayments::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(
+              Symbol,
+              Dodopayments::DiscountCreateParams::CustomerEligibility
+            )
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        ANY =
+          T.let(
+            :any,
+            Dodopayments::DiscountCreateParams::CustomerEligibility::TaggedSymbol
+          )
+        FIRST_TIME =
+          T.let(
+            :first_time,
+            Dodopayments::DiscountCreateParams::CustomerEligibility::TaggedSymbol
+          )
+        EXISTING =
+          T.let(
+            :existing,
+            Dodopayments::DiscountCreateParams::CustomerEligibility::TaggedSymbol
+          )
+        SPECIFIC =
+          T.let(
+            :specific,
+            Dodopayments::DiscountCreateParams::CustomerEligibility::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              Dodopayments::DiscountCreateParams::CustomerEligibility::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
     end
   end
 end

data/rbi/dodopayments/models/discount_list_params.rbi

@@ -14,7 +14,9 @@ module Dodopayments
           )
         end
 
-      # Filter by active status (true = not expired, false = expired)
+      # Filter by active status. `true` = currently redeemable (started, not expired,
+      # not usage-exhausted). `false` = not currently redeemable (expired,
+      # usage-exhausted, or pending a future `starts_at`).
       sig { returns(T.nilable(T::Boolean)) }
       attr_reader :active
 
@@ -68,7 +70,9 @@ module Dodopayments
         ).returns(T.attached_class)
       end
       def self.new(
-        # Filter by active status (true = not expired, false = expired)
+        # Filter by active status. `true` = currently redeemable (started, not expired,
+        # not usage-exhausted). `false` = not currently redeemable (expired,
+        # usage-exhausted, or pending a future `starts_at`).
         active: nil,
         # Filter by discount code (partial match, case-insensitive)
         code: nil,

data/rbi/dodopayments/models/discount_type.rbi

@@ -8,6 +8,7 @@ module Dodopayments
       TaggedSymbol = T.type_alias { T.all(Symbol, Dodopayments::DiscountType) }
       OrSymbol = T.type_alias { T.any(Symbol, String) }
 
+      FLAT = T.let(:flat, Dodopayments::DiscountType::TaggedSymbol)
       PERCENTAGE = T.let(:percentage, Dodopayments::DiscountType::TaggedSymbol)
 
       sig do