dodopayments 2.20.1 → 2.21.0

data/rbi/dodopayments/models/discount_update_params.rbi

@@ -28,6 +28,29 @@ module Dodopayments
       sig { returns(T.nilable(String)) }
       attr_accessor :code
 
+      # If present, fully replaces the discount's currency options (replace-set
+      # semantics, like `restricted_to`). Send an empty array to clear them.
+      sig do
+        returns(
+          T.nilable(
+            T::Array[Dodopayments::DiscountUpdateParams::CurrencyOption]
+          )
+        )
+      end
+      attr_accessor :currency_options
+
+      # If present, update who may redeem this discount. Plain field (not
+      # double-option): the DB column is `NOT NULL`, so it can never be cleared back to
+      # unset, only changed to another `CustomerEligibility` value.
+      sig do
+        returns(
+          T.nilable(
+            Dodopayments::DiscountUpdateParams::CustomerEligibility::OrSymbol
+          )
+        )
+      end
+      attr_accessor :customer_eligibility
+
       sig { returns(T.nilable(Time)) }
       attr_accessor :expires_at
 
@@ -42,6 +65,12 @@ module Dodopayments
       sig { returns(T.nilable(String)) }
       attr_accessor :name
 
+      # If present, update the per-customer usage limit (double-option: send `null` to
+      # clear it back to unlimited). Must be `<= usage_limit` (the value in effect after
+      # this patch) 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. If
       # not provided, the existing value is kept.
       sig { returns(T.nilable(T::Boolean)) }
@@ -52,13 +81,17 @@ module Dodopayments
       sig { returns(T.nilable(T::Array[String])) }
       attr_accessor :restricted_to
 
+      # If present, update `starts_at` (double-option: send `null` to clear it).
+      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.
       sig { returns(T.nilable(Integer)) }
       attr_accessor :subscription_cycles
 
-      # If present, update the discount type. Currently only `percentage` is supported.
+      # If present, update the discount type (`percentage` or `flat`).
       sig { returns(T.nilable(Dodopayments::DiscountType::OrSymbol)) }
       attr_accessor :type
 
@@ -70,12 +103,24 @@ module Dodopayments
           discount_id: String,
           amount: T.nilable(Integer),
           code: T.nilable(String),
+          currency_options:
+            T.nilable(
+              T::Array[
+                Dodopayments::DiscountUpdateParams::CurrencyOption::OrHash
+              ]
+            ),
+          customer_eligibility:
+            T.nilable(
+              Dodopayments::DiscountUpdateParams::CustomerEligibility::OrSymbol
+            ),
           expires_at: T.nilable(Time),
           metadata:
             T.nilable(T::Hash[Symbol, Dodopayments::MetadataItem::Variants]),
           name: T.nilable(String),
+          per_customer_usage_limit: T.nilable(Integer),
           preserve_on_plan_change: T.nilable(T::Boolean),
           restricted_to: T.nilable(T::Array[String]),
+          starts_at: T.nilable(Time),
           subscription_cycles: T.nilable(Integer),
           type: T.nilable(Dodopayments::DiscountType::OrSymbol),
           usage_limit: T.nilable(Integer),
@@ -91,21 +136,34 @@ module Dodopayments
         amount: nil,
         # If present, update the discount code (uppercase).
         code: nil,
+        # If present, fully replaces the discount's currency options (replace-set
+        # semantics, like `restricted_to`). Send an empty array to clear them.
+        currency_options: nil,
+        # If present, update who may redeem this discount. Plain field (not
+        # double-option): the DB column is `NOT NULL`, so it can never be cleared back to
+        # unset, only changed to another `CustomerEligibility` value.
+        customer_eligibility: nil,
         expires_at: nil,
         # Additional metadata for the discount
         metadata: nil,
         name: nil,
+        # If present, update the per-customer usage limit (double-option: send `null` to
+        # clear it back to unlimited). Must be `<= usage_limit` (the value in effect after
+        # this patch) when both are set.
+        per_customer_usage_limit: nil,
         # Whether this discount should be preserved when a subscription changes plans. If
         # not provided, the existing value is kept.
         preserve_on_plan_change: nil,
         # If present, replaces all restricted product IDs with this new set. To remove all
         # restrictions, send empty array
         restricted_to: nil,
+        # If present, update `starts_at` (double-option: send `null` to clear it).
+        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.
         subscription_cycles: nil,
-        # If present, update the discount type. Currently only `percentage` is supported.
+        # If present, update the discount type (`percentage` or `flat`).
         type: nil,
         usage_limit: nil,
         request_options: {}
@@ -118,12 +176,22 @@ module Dodopayments
             discount_id: String,
             amount: T.nilable(Integer),
             code: T.nilable(String),
+            currency_options:
+              T.nilable(
+                T::Array[Dodopayments::DiscountUpdateParams::CurrencyOption]
+              ),
+            customer_eligibility:
+              T.nilable(
+                Dodopayments::DiscountUpdateParams::CustomerEligibility::OrSymbol
+              ),
             expires_at: T.nilable(Time),
             metadata:
               T.nilable(T::Hash[Symbol, Dodopayments::MetadataItem::Variants]),
             name: T.nilable(String),
+            per_customer_usage_limit: T.nilable(Integer),
             preserve_on_plan_change: T.nilable(T::Boolean),
             restricted_to: T.nilable(T::Array[String]),
+            starts_at: T.nilable(Time),
             subscription_cycles: T.nilable(Integer),
             type: T.nilable(Dodopayments::DiscountType::OrSymbol),
             usage_limit: T.nilable(Integer),
@@ -133,6 +201,129 @@ module Dodopayments
       end
       def to_hash
       end
+
+      class CurrencyOption < Dodopayments::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Dodopayments::DiscountUpdateParams::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
+
+      # If present, update who may redeem this discount. Plain field (not
+      # double-option): the DB column is `NOT NULL`, so it can never be cleared back to
+      # unset, only changed to another `CustomerEligibility` value.
+      module CustomerEligibility
+        extend Dodopayments::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(
+              Symbol,
+              Dodopayments::DiscountUpdateParams::CustomerEligibility
+            )
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        ANY =
+          T.let(
+            :any,
+            Dodopayments::DiscountUpdateParams::CustomerEligibility::TaggedSymbol
+          )
+        FIRST_TIME =
+          T.let(
+            :first_time,
+            Dodopayments::DiscountUpdateParams::CustomerEligibility::TaggedSymbol
+          )
+        EXISTING =
+          T.let(
+            :existing,
+            Dodopayments::DiscountUpdateParams::CustomerEligibility::TaggedSymbol
+          )
+        SPECIFIC =
+          T.let(
+            :specific,
+            Dodopayments::DiscountUpdateParams::CustomerEligibility::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              Dodopayments::DiscountUpdateParams::CustomerEligibility::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
     end
   end
 end

data/rbi/dodopayments/models/payment.rbi

@@ -139,6 +139,22 @@ module Dodopayments
       sig { returns(T.nilable(String)) }
       attr_accessor :error_message
 
+      # Purpose-built failure messaging for the merchant and the customer, derived from
+      # `error_code`. Present whenever `error_code` is set, regardless of payment
+      # status; unrecognised codes still resolve via a generic fallback rather than
+      # being omitted. The customer copy is always generic for fraud-sensitive declines
+      # (lost/stolen/pickup/fraudulent) so the true reason is never leaked.
+      sig { returns(T.nilable(Dodopayments::Payment::FailureDetails)) }
+      attr_reader :failure_details
+
+      sig do
+        params(
+          failure_details:
+            T.nilable(Dodopayments::Payment::FailureDetails::OrHash)
+        ).void
+      end
+      attr_writer :failure_details
+
       # Invoice ID for this payment. Uses India-specific invoice ID if available.
       sig { returns(T.nilable(String)) }
       attr_accessor :invoice_id
@@ -228,6 +244,8 @@ module Dodopayments
           discounts: T.nilable(T::Array[Dodopayments::DiscountDetail::OrHash]),
           error_code: T.nilable(String),
           error_message: T.nilable(String),
+          failure_details:
+            T.nilable(Dodopayments::Payment::FailureDetails::OrHash),
           invoice_id: T.nilable(String),
           invoice_url: T.nilable(String),
           payment_link: T.nilable(String),
@@ -312,6 +330,12 @@ module Dodopayments
         error_code: nil,
         # An error message if the payment failed
         error_message: nil,
+        # Purpose-built failure messaging for the merchant and the customer, derived from
+        # `error_code`. Present whenever `error_code` is set, regardless of payment
+        # status; unrecognised codes still resolve via a generic fallback rather than
+        # being omitted. The customer copy is always generic for fraud-sensitive declines
+        # (lost/stolen/pickup/fraudulent) so the true reason is never leaked.
+        failure_details: 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.
@@ -379,6 +403,7 @@ module Dodopayments
             discounts: T.nilable(T::Array[Dodopayments::DiscountDetail]),
             error_code: T.nilable(String),
             error_message: T.nilable(String),
+            failure_details: T.nilable(Dodopayments::Payment::FailureDetails),
             invoice_id: T.nilable(String),
             invoice_url: T.nilable(String),
             payment_link: T.nilable(String),
@@ -425,6 +450,328 @@ module Dodopayments
         end
       end
 
+      class FailureDetails < Dodopayments::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Dodopayments::Payment::FailureDetails,
+              Dodopayments::Internal::AnyHash
+            )
+          end
+
+        # The unified error code (echoes `error_code`).
+        sig { returns(String) }
+        attr_accessor :code
+
+        # The primary CTA to show the customer.
+        sig do
+          returns(
+            Dodopayments::Payment::FailureDetails::CustomerCta::TaggedSymbol
+          )
+        end
+        attr_accessor :customer_cta
+
+        # Whether the customer can resolve this themselves (e.g. fix CVC).
+        sig { returns(T::Boolean) }
+        attr_accessor :customer_fixable
+
+        # The customer-facing string. Always generic (`C11`) for the fraud-4.
+        sig { returns(String) }
+        attr_accessor :customer_message
+
+        # The customer message template identifier (C1..C20).
+        sig do
+          returns(
+            Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+          )
+        end
+        attr_accessor :customer_template
+
+        # Soft or hard decline.
+        sig do
+          returns(
+            Dodopayments::Payment::FailureDetails::DeclineType::TaggedSymbol
+          )
+        end
+        attr_accessor :decline_type
+
+        # Merchant-facing headline + recommended action (Payment Details). For the fraud-4
+        # this includes the operator "do not reveal" warning.
+        sig { returns(String) }
+        attr_accessor :merchant_message
+
+        # Purpose-built failure messaging for the merchant and the customer, derived from
+        # `error_code`. Present whenever `error_code` is set, regardless of payment
+        # status; unrecognised codes still resolve via a generic fallback rather than
+        # being omitted. The customer copy is always generic for fraud-sensitive declines
+        # (lost/stolen/pickup/fraudulent) so the true reason is never leaked.
+        sig do
+          params(
+            code: String,
+            customer_cta:
+              Dodopayments::Payment::FailureDetails::CustomerCta::OrSymbol,
+            customer_fixable: T::Boolean,
+            customer_message: String,
+            customer_template:
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::OrSymbol,
+            decline_type:
+              Dodopayments::Payment::FailureDetails::DeclineType::OrSymbol,
+            merchant_message: String
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The unified error code (echoes `error_code`).
+          code:,
+          # The primary CTA to show the customer.
+          customer_cta:,
+          # Whether the customer can resolve this themselves (e.g. fix CVC).
+          customer_fixable:,
+          # The customer-facing string. Always generic (`C11`) for the fraud-4.
+          customer_message:,
+          # The customer message template identifier (C1..C20).
+          customer_template:,
+          # Soft or hard decline.
+          decline_type:,
+          # Merchant-facing headline + recommended action (Payment Details). For the fraud-4
+          # this includes the operator "do not reveal" warning.
+          merchant_message:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              code: String,
+              customer_cta:
+                Dodopayments::Payment::FailureDetails::CustomerCta::TaggedSymbol,
+              customer_fixable: T::Boolean,
+              customer_message: String,
+              customer_template:
+                Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol,
+              decline_type:
+                Dodopayments::Payment::FailureDetails::DeclineType::TaggedSymbol,
+              merchant_message: String
+            }
+          )
+        end
+        def to_hash
+        end
+
+        # The primary CTA to show the customer.
+        module CustomerCta
+          extend Dodopayments::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, Dodopayments::Payment::FailureDetails::CustomerCta)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          EDIT_AND_RETRY =
+            T.let(
+              :edit_and_retry,
+              Dodopayments::Payment::FailureDetails::CustomerCta::TaggedSymbol
+            )
+          USE_ANOTHER_METHOD =
+            T.let(
+              :use_another_method,
+              Dodopayments::Payment::FailureDetails::CustomerCta::TaggedSymbol
+            )
+          TRY_AGAIN =
+            T.let(
+              :try_again,
+              Dodopayments::Payment::FailureDetails::CustomerCta::TaggedSymbol
+            )
+          TRY_LATER =
+            T.let(
+              :try_later,
+              Dodopayments::Payment::FailureDetails::CustomerCta::TaggedSymbol
+            )
+          RETRY_AND_VERIFY =
+            T.let(
+              :retry_and_verify,
+              Dodopayments::Payment::FailureDetails::CustomerCta::TaggedSymbol
+            )
+          RESTART =
+            T.let(
+              :restart,
+              Dodopayments::Payment::FailureDetails::CustomerCta::TaggedSymbol
+            )
+          UPDATE_METHOD =
+            T.let(
+              :update_method,
+              Dodopayments::Payment::FailureDetails::CustomerCta::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Dodopayments::Payment::FailureDetails::CustomerCta::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+
+        # The customer message template identifier (C1..C20).
+        module CustomerTemplate
+          extend Dodopayments::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                Dodopayments::Payment::FailureDetails::CustomerTemplate
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          C1 =
+            T.let(
+              :C1,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C2 =
+            T.let(
+              :C2,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C3 =
+            T.let(
+              :C3,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C4 =
+            T.let(
+              :C4,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C5 =
+            T.let(
+              :C5,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C6 =
+            T.let(
+              :C6,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C7 =
+            T.let(
+              :C7,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C8 =
+            T.let(
+              :C8,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C9 =
+            T.let(
+              :C9,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C10 =
+            T.let(
+              :C10,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C11 =
+            T.let(
+              :C11,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C12 =
+            T.let(
+              :C12,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C13 =
+            T.let(
+              :C13,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C14 =
+            T.let(
+              :C14,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C15 =
+            T.let(
+              :C15,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C16 =
+            T.let(
+              :C16,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C17 =
+            T.let(
+              :C17,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C18 =
+            T.let(
+              :C18,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C19 =
+            T.let(
+              :C19,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+          C20 =
+            T.let(
+              :C20,
+              Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Dodopayments::Payment::FailureDetails::CustomerTemplate::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+
+        # Soft or hard decline.
+        module DeclineType
+          extend Dodopayments::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, Dodopayments::Payment::FailureDetails::DeclineType)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          SOFT =
+            T.let(
+              :soft,
+              Dodopayments::Payment::FailureDetails::DeclineType::TaggedSymbol
+            )
+          HARD =
+            T.let(
+              :hard,
+              Dodopayments::Payment::FailureDetails::DeclineType::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Dodopayments::Payment::FailureDetails::DeclineType::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+
       class ProductCart < Dodopayments::Internal::Type::BaseModel
         OrHash =
           T.type_alias do