dodopayments 2.33.0 → 2.34.0

data/lib/dodopayments/models/product_collections/group_update_params.rb

@@ -20,7 +20,8 @@ module Dodopayments
 
         # @!attribute group_name
         #   Optional group name update: Some(Some(name)) = set name, Some(None) = clear
-        #   name, None = no change
+        #   name, None = no change The API returns 422 if another group in the collection
+        #   has no name.
         #
         #   @return [String, nil]
         optional :group_name, String, nil?: true

data/lib/dodopayments/models/subscription_service_period.rb

@@ -9,6 +9,15 @@ module Dodopayments
       #   @return [Time]
       required :ends_at, Time
 
+      # @!attribute proration_factor
+      #   The part of one full billing period that the plan charge pays for. The value
+      #   `"1"` is a full period. A value less than 1 is a partial period, for example
+      #   after a plan change that keeps the billing cycle. For a plan change, this is the
+      #   value of the new plan. The credit for the old plan is not in this value.
+      #
+      #   @return [String]
+      required :proration_factor, String
+
       # @!attribute starts_at
       #   Start of the service period. For a renewal, this is the billing date. For a plan
       #   change that applies at the next billing date, this is the time when the change
@@ -23,7 +32,7 @@ module Dodopayments
       #   @return [String]
       required :subscription_id, String
 
-      # @!method initialize(ends_at:, starts_at:, subscription_id:)
+      # @!method initialize(ends_at:, proration_factor:, starts_at:, subscription_id:)
       #   Some parameter documentations has been truncated, see
       #   {Dodopayments::Models::SubscriptionServicePeriod} for more details.
       #
@@ -31,6 +40,8 @@ module Dodopayments
       #
       #   @param ends_at [Time] End of the service period.
       #
+      #   @param proration_factor [String] The part of one full billing period that the plan charge pays for. The value
+      #
       #   @param starts_at [Time] Start of the service period. For a renewal, this is the billing date. For a
       #
       #   @param subscription_id [String] Identifier of the subscription.

data/lib/dodopayments/models.rb

@@ -95,6 +95,8 @@ module Dodopayments
 
   CbbProrationBehavior = Dodopayments::Models::CbbProrationBehavior
 
+  ChargeType = Dodopayments::Models::ChargeType
+
   CheckoutSessionBillingAddress = Dodopayments::Models::CheckoutSessionBillingAddress
 
   CheckoutSessionCreateParams = Dodopayments::Models::CheckoutSessionCreateParams

data/lib/dodopayments/resources/invoices/payments.rb

@@ -4,60 +4,84 @@ module Dodopayments
   module Resources
     class Invoices
       class Payments
-        # @overload retrieve(payment_id, request_options: {})
+        # Some parameter documentations has been truncated, see
+        # {Dodopayments::Models::Invoices::PaymentRetrieveParams} for more details.
+        #
+        # @overload retrieve(payment_id, token: nil, request_options: {})
         #
         # @param payment_id [String] Payment ID
         #
+        # @param token [String] The signed link token. If the business asks for a credential on its invoice link
+        #
         # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [StringIO]
         #
         # @see Dodopayments::Models::Invoices::PaymentRetrieveParams
         def retrieve(payment_id, params = {})
+          parsed, options = Dodopayments::Invoices::PaymentRetrieveParams.dump_request(params)
+          query = Dodopayments::Internal::Util.encode_query_params(parsed)
           @client.request(
             method: :get,
             path: ["invoices/payments/%1$s", payment_id],
+            query: query,
             headers: {"accept" => "application/pdf"},
             model: StringIO,
-            options: params[:request_options]
+            options: options
           )
         end
 
-        # @overload retrieve_payout(payout_id, request_options: {})
+        # Some parameter documentations has been truncated, see
+        # {Dodopayments::Models::Invoices::PaymentRetrievePayoutParams} for more details.
+        #
+        # @overload retrieve_payout(payout_id, token: nil, request_options: {})
         #
         # @param payout_id [String] Payout ID
         #
+        # @param token [String] The signed link token. If the business asks for a credential on its invoice link
+        #
         # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [StringIO]
         #
         # @see Dodopayments::Models::Invoices::PaymentRetrievePayoutParams
         def retrieve_payout(payout_id, params = {})
+          parsed, options = Dodopayments::Invoices::PaymentRetrievePayoutParams.dump_request(params)
+          query = Dodopayments::Internal::Util.encode_query_params(parsed)
           @client.request(
             method: :get,
             path: ["invoices/payouts/%1$s", payout_id],
+            query: query,
             headers: {"accept" => "application/pdf"},
             model: StringIO,
-            options: params[:request_options]
+            options: options
           )
         end
 
-        # @overload retrieve_refund(refund_id, request_options: {})
+        # Some parameter documentations has been truncated, see
+        # {Dodopayments::Models::Invoices::PaymentRetrieveRefundParams} for more details.
+        #
+        # @overload retrieve_refund(refund_id, token: nil, request_options: {})
         #
         # @param refund_id [String] Refund ID
         #
+        # @param token [String] The signed link token. If the business asks for a credential on its invoice link
+        #
         # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [StringIO]
         #
         # @see Dodopayments::Models::Invoices::PaymentRetrieveRefundParams
         def retrieve_refund(refund_id, params = {})
+          parsed, options = Dodopayments::Invoices::PaymentRetrieveRefundParams.dump_request(params)
+          query = Dodopayments::Internal::Util.encode_query_params(parsed)
           @client.request(
             method: :get,
             path: ["invoices/refunds/%1$s", refund_id],
+            query: query,
             headers: {"accept" => "application/pdf"},
             model: StringIO,
-            options: params[:request_options]
+            options: options
           )
         end
 

data/lib/dodopayments/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dodopayments
-  VERSION = "2.33.0"
+  VERSION = "2.34.0"
 end

data/lib/dodopayments.rb

@@ -110,6 +110,7 @@ require_relative "dodopayments/models/brand_update_params"
 require_relative "dodopayments/models/cancellation_feedback"
 require_relative "dodopayments/models/cbb_overage_behavior"
 require_relative "dodopayments/models/cbb_proration_behavior"
+require_relative "dodopayments/models/charge_type"
 require_relative "dodopayments/models/checkout_session_billing_address"
 require_relative "dodopayments/models/checkout_session_create_params"
 require_relative "dodopayments/models/checkout_session_customization"

data/rbi/dodopayments/models/charge_type.rbi

@@ -0,0 +1,37 @@
+# typed: strong
+
+module Dodopayments
+  module Models
+    # The type of subscription charge that a payment is for.
+    #
+    # A payment has one invoice, and the invoice has one type. Thus each payment has
+    # one charge type. A payment that charges no subscription has no charge type.
+    #
+    # - `new`: the first payment of one or more subscriptions. A retry of that payment
+    #   is also `new`. A cart with new subscriptions and one-time products is `new`.
+    #   Read the one-time products from `product_cart`.
+    # - `renewal`: a charge at the billing date. A dunning retry and a manual retry of
+    #   that charge are also `renewal`. A `renewal` does not always extend the service
+    #   period. For example, the usage settlement of a paused subscription is a
+    #   `renewal` with `includes_usage` true and no entry in `service_periods`.
+    #   Examine `service_periods` before you extend access.
+    # - `plan_change`: a charge for a plan change. The change applies now or at the
+    #   next billing date.
+    # - `on_demand`: an on-demand charge of an on-demand subscription.
+    module ChargeType
+      extend Dodopayments::Internal::Type::Enum
+
+      TaggedSymbol = T.type_alias { T.all(Symbol, Dodopayments::ChargeType) }
+      OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+      NEW = T.let(:new, Dodopayments::ChargeType::TaggedSymbol)
+      RENEWAL = T.let(:renewal, Dodopayments::ChargeType::TaggedSymbol)
+      PLAN_CHANGE = T.let(:plan_change, Dodopayments::ChargeType::TaggedSymbol)
+      ON_DEMAND = T.let(:on_demand, Dodopayments::ChargeType::TaggedSymbol)
+
+      sig { override.returns(T::Array[Dodopayments::ChargeType::TaggedSymbol]) }
+      def self.values
+      end
+    end
+  end
+end

data/rbi/dodopayments/models/checkout_session_preview_response.rbi

@@ -409,6 +409,13 @@ module Dodopayments
         sig { returns(T.nilable(Integer)) }
         attr_accessor :discount_cycle
 
+        # The monthly equivalent of the yearly unit price after discounts, in minor units
+        # of `currency`. Only the hosted checkout sets it, when the business shows yearly
+        # plans as monthly. The value is only for display. The order summary shows the
+        # amounts that we charge.
+        sig { returns(T.nilable(Integer)) }
+        attr_accessor :monthly_equivalent
+
         # name of the product
         sig { returns(T.nilable(String)) }
         attr_accessor :name
@@ -447,6 +454,7 @@ module Dodopayments
             description: T.nilable(String),
             discount_amount: T.nilable(Integer),
             discount_cycle: T.nilable(Integer),
+            monthly_equivalent: T.nilable(Integer),
             name: T.nilable(String),
             tax: T.nilable(Integer)
           ).returns(T.attached_class)
@@ -483,6 +491,11 @@ module Dodopayments
           discount_amount: nil,
           # number of cycles the discount will apply
           discount_cycle: nil,
+          # The monthly equivalent of the yearly unit price after discounts, in minor units
+          # of `currency`. Only the hosted checkout sets it, when the business shows yearly
+          # plans as monthly. The value is only for display. The order summary shows the
+          # amounts that we charge.
+          monthly_equivalent: nil,
           # name of the product
           name: nil,
           # total tax
@@ -521,6 +534,7 @@ module Dodopayments
               description: T.nilable(String),
               discount_amount: T.nilable(Integer),
               discount_cycle: T.nilable(Integer),
+              monthly_equivalent: T.nilable(Integer),
               name: T.nilable(String),
               tax: T.nilable(Integer)
             }

data/rbi/dodopayments/models/invoices/payment_retrieve_params.rbi

@@ -18,19 +18,35 @@ module Dodopayments
         sig { returns(String) }
         attr_accessor :payment_id
 
+        # The signed link token. If the business asks for a credential on its invoice
+        # links, a valid token for this record replaces the credential.
+        sig { returns(T.nilable(String)) }
+        attr_reader :token
+
+        sig { params(token: String).void }
+        attr_writer :token
+
         sig do
           params(
             payment_id: String,
+            token: String,
             request_options: Dodopayments::RequestOptions::OrHash
           ).returns(T.attached_class)
         end
-        def self.new(payment_id:, request_options: {})
+        def self.new(
+          payment_id:,
+          # The signed link token. If the business asks for a credential on its invoice
+          # links, a valid token for this record replaces the credential.
+          token: nil,
+          request_options: {}
+        )
         end
 
         sig do
           override.returns(
             {
               payment_id: String,
+              token: String,
               request_options: Dodopayments::RequestOptions
             }
           )

data/rbi/dodopayments/models/invoices/payment_retrieve_payout_params.rbi

@@ -18,18 +18,37 @@ module Dodopayments
         sig { returns(String) }
         attr_accessor :payout_id
 
+        # The signed link token. If the business asks for a credential on its invoice
+        # links, a valid token for this record replaces the credential.
+        sig { returns(T.nilable(String)) }
+        attr_reader :token
+
+        sig { params(token: String).void }
+        attr_writer :token
+
         sig do
           params(
             payout_id: String,
+            token: String,
             request_options: Dodopayments::RequestOptions::OrHash
           ).returns(T.attached_class)
         end
-        def self.new(payout_id:, request_options: {})
+        def self.new(
+          payout_id:,
+          # The signed link token. If the business asks for a credential on its invoice
+          # links, a valid token for this record replaces the credential.
+          token: nil,
+          request_options: {}
+        )
         end
 
         sig do
           override.returns(
-            { payout_id: String, request_options: Dodopayments::RequestOptions }
+            {
+              payout_id: String,
+              token: String,
+              request_options: Dodopayments::RequestOptions
+            }
           )
         end
         def to_hash

data/rbi/dodopayments/models/invoices/payment_retrieve_refund_params.rbi

@@ -18,18 +18,37 @@ module Dodopayments
         sig { returns(String) }
         attr_accessor :refund_id
 
+        # The signed link token. If the business asks for a credential on its invoice
+        # links, a valid token for this record replaces the credential.
+        sig { returns(T.nilable(String)) }
+        attr_reader :token
+
+        sig { params(token: String).void }
+        attr_writer :token
+
         sig do
           params(
             refund_id: String,
+            token: String,
             request_options: Dodopayments::RequestOptions::OrHash
           ).returns(T.attached_class)
         end
-        def self.new(refund_id:, request_options: {})
+        def self.new(
+          refund_id:,
+          # The signed link token. If the business asks for a credential on its invoice
+          # links, a valid token for this record replaces the credential.
+          token: nil,
+          request_options: {}
+        )
         end
 
         sig do
           override.returns(
-            { refund_id: String, request_options: Dodopayments::RequestOptions }
+            {
+              refund_id: String,
+              token: String,
+              request_options: Dodopayments::RequestOptions
+            }
           )
         end
         def to_hash

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.
@@ -86,7 +92,10 @@ module Dodopayments
       # 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.
+      # 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
 
@@ -114,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
@@ -126,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)) }
@@ -165,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
 
@@ -231,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],
@@ -244,11 +276,14 @@ module Dodopayments
           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]),
@@ -289,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.
@@ -313,7 +352,10 @@ module Dodopayments
         # 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.
+        # 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
@@ -331,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,
@@ -358,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,
@@ -402,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],
@@ -415,12 +474,15 @@ module Dodopayments
             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]),