dodopayments 2.33.0 → 2.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27eda33527f7fc36507b133919bcf76f5bfe1d537e875e0ed762c3b3fd5aad53
-  data.tar.gz: 904efd6de1bbdc9e54a65483709a8d9d3c7f0b4496011d46e9f69bb753e26083
+  metadata.gz: c11a0d8230c984a0f1edb90a4ec17367c959b1184fb237167022cce1ffabef79
+  data.tar.gz: 65a53d9ea3bef5ff6f6ac1246ad5f58bf661299376465bd244cf89dc46518d6b
 SHA512:
-  metadata.gz: b4eb25c02f04ca12ea6b41f3b3d254d7afbdce14137dd5213b52994d172b227ec5a87db193a6ed4c0330fcda867f79e522a1b0f74ebc6e6a8e23d81dc2615bab
-  data.tar.gz: f72f531842560027f90d5fc5ec789025487305ec95993829a79b704210803d81cb8a33c357cb09a79be7abef9e030673b325663a2d27b6427d78737ade894f0e
+  metadata.gz: 143d2ca167230b620f7fbce7e95bcb0ab604194841690113dd8c58609643d2faf141935105139492e60aa297ccfa70ac896f6b11b1334dcb934f67f6aaa280fd
+  data.tar.gz: b57185159507e699991b8bc47b7a8559260179cc013dadbd48e60bdb17d3d8108a31c689ec8c96bc308a631bac669ad5d09e9f3fab8aecb43718ce42adb95273

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.34.0](https://github.com/dodopayments/dodopayments-ruby/compare/v2.33.0...v2.34.0) (2026-10-21)
+
+
+### Features
+
+* **api:** payment charge type, usage flag and card details, signed invoice link tokens ([3b6eb1d](https://github.com/dodopayments/dodopayments-ruby/commit/3b6eb1d46ca7c02d279ab66c62a746e8df1f14d3))
+* **api:** payment charge type, usage flag and card details, signed invoice link tokens ([f3d6720](https://github.com/dodopayments/dodopayments-ruby/commit/f3d67205537089c45bd7643f399bece43a7d56f5))
+
 ## [2.33.0](https://github.com/dodopayments/dodopayments-ruby/compare/v2.32.2...v2.33.0) (2026-10-14)
 
 

data/README.md

@@ -23,7 +23,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "dodopayments", "~> 2.33.0"
+gem "dodopayments", "~> 2.34.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/dodopayments/internal/type/enum.rb

@@ -17,28 +17,28 @@ module Dodopayments
       # values safely.
       #
       # @example
-      #   # `intent_status` is a `Dodopayments::IntentStatus`
-      #   case intent_status
-      #   when Dodopayments::IntentStatus::SUCCEEDED
+      #   # `charge_type` is a `Dodopayments::ChargeType`
+      #   case charge_type
+      #   when Dodopayments::ChargeType::NEW
       #     # ...
-      #   when Dodopayments::IntentStatus::FAILED
+      #   when Dodopayments::ChargeType::RENEWAL
       #     # ...
-      #   when Dodopayments::IntentStatus::CANCELLED
+      #   when Dodopayments::ChargeType::PLAN_CHANGE
       #     # ...
       #   else
-      #     puts(intent_status)
+      #     puts(charge_type)
       #   end
       #
       # @example
-      #   case intent_status
-      #   in :succeeded
+      #   case charge_type
+      #   in :new
       #     # ...
-      #   in :failed
+      #   in :renewal
       #     # ...
-      #   in :cancelled
+      #   in :plan_change
       #     # ...
       #   else
-      #     puts(intent_status)
+      #     puts(charge_type)
       #   end
       module Enum
         include Dodopayments::Internal::Type::Converter

data/lib/dodopayments/models/charge_type.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+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
+
+      NEW = :new
+      RENEWAL = :renewal
+      PLAN_CHANGE = :plan_change
+      ON_DEMAND = :on_demand
+
+      # @!method self.values
+      #   @return [Array<Symbol>]
+    end
+  end
+end

data/lib/dodopayments/models/checkout_session_preview_response.rb

@@ -301,6 +301,15 @@ module Dodopayments
         #   @return [Integer, nil]
         optional :discount_cycle, Integer, nil?: true
 
+        # @!attribute monthly_equivalent
+        #   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.
+        #
+        #   @return [Integer, nil]
+        optional :monthly_equivalent, Integer, nil?: true
+
         # @!attribute name
         #   name of the product
         #
@@ -313,7 +322,7 @@ module Dodopayments
         #   @return [Integer, nil]
         optional :tax, Integer, nil?: true
 
-        # @!method initialize(credit_entitlements:, currency:, discounted_price:, is_subscription:, is_usage_based:, meters:, og_currency:, og_price:, product_id:, quantity:, tax_category:, tax_inclusive:, tax_rate:, addons: nil, description: nil, discount_amount: nil, discount_cycle: nil, name: nil, tax: nil)
+        # @!method initialize(credit_entitlements:, currency:, discounted_price:, is_subscription:, is_usage_based:, meters:, og_currency:, og_price:, product_id:, quantity:, tax_category:, tax_inclusive:, tax_rate:, addons: nil, description: nil, discount_amount: nil, discount_cycle: nil, monthly_equivalent: nil, name: nil, tax: nil)
         #   Some parameter documentations has been truncated, see
         #   {Dodopayments::Models::CheckoutSessionPreviewResponse::ProductCart} for more
         #   details.
@@ -352,6 +361,8 @@ module Dodopayments
         #
         #   @param discount_cycle [Integer, nil] number of cycles the discount will apply
         #
+        #   @param monthly_equivalent [Integer, nil] The monthly equivalent of the yearly unit price after discounts, in minor units
+        #
         #   @param name [String, nil] name of the product
         #
         #   @param tax [Integer, nil] total tax

data/lib/dodopayments/models/invoices/payment_retrieve_params.rb

@@ -13,8 +13,21 @@ module Dodopayments
         #   @return [String]
         required :payment_id, String
 
-        # @!method initialize(payment_id:, request_options: {})
+        # @!attribute token
+        #   The signed link token. If the business asks for a credential on its invoice
+        #   links, a valid token for this record replaces the credential.
+        #
+        #   @return [String, nil]
+        optional :token, String
+
+        # @!method initialize(payment_id:, token: nil, request_options: {})
+        #   Some parameter documentations has been truncated, see
+        #   {Dodopayments::Models::Invoices::PaymentRetrieveParams} for more details.
+        #
         #   @param payment_id [String]
+        #
+        #   @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}]
       end
     end

data/lib/dodopayments/models/invoices/payment_retrieve_payout_params.rb

@@ -13,8 +13,21 @@ module Dodopayments
         #   @return [String]
         required :payout_id, String
 
-        # @!method initialize(payout_id:, request_options: {})
+        # @!attribute token
+        #   The signed link token. If the business asks for a credential on its invoice
+        #   links, a valid token for this record replaces the credential.
+        #
+        #   @return [String, nil]
+        optional :token, String
+
+        # @!method initialize(payout_id:, token: nil, request_options: {})
+        #   Some parameter documentations has been truncated, see
+        #   {Dodopayments::Models::Invoices::PaymentRetrievePayoutParams} for more details.
+        #
         #   @param payout_id [String]
+        #
+        #   @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}]
       end
     end

data/lib/dodopayments/models/invoices/payment_retrieve_refund_params.rb

@@ -13,8 +13,21 @@ module Dodopayments
         #   @return [String]
         required :refund_id, String
 
-        # @!method initialize(refund_id:, request_options: {})
+        # @!attribute token
+        #   The signed link token. If the business asks for a credential on its invoice
+        #   links, a valid token for this record replaces the credential.
+        #
+        #   @return [String, nil]
+        optional :token, String
+
+        # @!method initialize(refund_id:, token: nil, request_options: {})
+        #   Some parameter documentations has been truncated, see
+        #   {Dodopayments::Models::Invoices::PaymentRetrieveRefundParams} for more details.
+        #
         #   @param refund_id [String]
+        #
+        #   @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}]
       end
     end

data/lib/dodopayments/models/payment.rb

@@ -52,6 +52,14 @@ module Dodopayments
       #   @return [Array<Dodopayments::Models::Dispute>]
       required :disputes, -> { Dodopayments::Internal::Type::ArrayOf[Dodopayments::Dispute] }
 
+      # @!attribute includes_usage
+      #   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.
+      #
+      #   @return [Boolean]
+      required :includes_usage, Dodopayments::Internal::Type::Boolean
+
       # @!attribute is_multi_subscription
       #   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
@@ -105,7 +113,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.
       #
       #   @return [Array<Dodopayments::Models::SubscriptionServicePeriod>]
       required :service_periods,
@@ -143,6 +154,22 @@ module Dodopayments
       #   @return [Integer]
       required :total_amount, Integer
 
+      # @!attribute card_exp_month
+      #   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.
+      #
+      #   @return [String, nil]
+      optional :card_exp_month, String, nil?: true
+
+      # @!attribute card_exp_year
+      #   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.
+      #
+      #   @return [String, nil]
+      optional :card_exp_year, String, nil?: true
+
       # @!attribute card_holder_name
       #   Cardholder name
       #
@@ -162,17 +189,27 @@ module Dodopayments
       optional :card_last_four, String, nil?: true
 
       # @!attribute card_network
-      #   Card network like VISA, MASTERCARD etc.
+      #   Card network, in lowercase, for example `visa`, `mastercard` or `amex`. Older
+      #   payments can carry other casing.
       #
       #   @return [String, nil]
       optional :card_network, String, nil?: true
 
       # @!attribute card_type
-      #   The type of card DEBIT or CREDIT
+      #   The type of card, in lowercase: `credit`, `debit` or `prepaid`. Older payments
+      #   can carry other casing.
       #
       #   @return [String, nil]
       optional :card_type, String, nil?: true
 
+      # @!attribute charge_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.
+      #
+      #   @return [Symbol, Dodopayments::Models::ChargeType, nil]
+      optional :charge_type, enum: -> { Dodopayments::ChargeType }, nil?: true
+
       # @!attribute checkout_session_id
       #   If payment is made using a checkout session, this field is set to the id of the
       #   session.
@@ -225,7 +262,11 @@ module Dodopayments
       optional :invoice_id, String, nil?: true
 
       # @!attribute invoice_url
-      #   URL to download the invoice PDF for this payment.
+      #   @deprecated Use `GET /invoices/payments/{payment_id}` with an API key.
+      #
+      #   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.
       #
       #   @return [String, nil]
       optional :invoice_url, String, nil?: true
@@ -304,7 +345,7 @@ module Dodopayments
       #   @return [Time, nil]
       optional :updated_at, Time, nil?: true
 
-      # @!method initialize(billing:, brand_id:, business_id:, created_at:, currency:, customer:, digital_products_delivered:, disputes:, is_multi_subscription:, is_update_payment_method:, metadata:, payment_id:, payment_provider:, refunds:, retry_attempt:, service_periods:, settlement_amount:, settlement_currency:, subscription_ids:, total_amount:, card_holder_name: nil, card_issuing_country: nil, card_last_four: nil, card_network: nil, card_type: nil, checkout_session_id: nil, custom_field_responses: nil, discount_id: nil, discounts: nil, error_code: nil, error_message: nil, invoice_id: nil, invoice_url: nil, payment_link: nil, payment_method: nil, payment_method_id: nil, payment_method_type: nil, product_cart: nil, refund_status: nil, settlement_tax: nil, status: nil, subscription_id: nil, tax: nil, updated_at: nil)
+      # @!method initialize(billing:, brand_id:, business_id:, created_at:, currency:, customer:, digital_products_delivered:, disputes:, includes_usage:, is_multi_subscription:, is_update_payment_method:, metadata:, payment_id:, payment_provider:, refunds:, retry_attempt:, service_periods:, settlement_amount:, settlement_currency:, subscription_ids:, total_amount:, card_exp_month: nil, card_exp_year: nil, card_holder_name: nil, card_issuing_country: nil, card_last_four: nil, card_network: nil, card_type: nil, charge_type: nil, checkout_session_id: nil, custom_field_responses: nil, discount_id: nil, discounts: nil, error_code: nil, error_message: nil, invoice_id: nil, invoice_url: nil, payment_link: nil, payment_method: nil, payment_method_id: nil, payment_method_type: nil, product_cart: nil, refund_status: nil, settlement_tax: nil, status: nil, subscription_id: nil, tax: nil, updated_at: nil)
       #   Some parameter documentations has been truncated, see
       #   {Dodopayments::Models::Payment} for more details.
       #
@@ -324,6 +365,8 @@ module Dodopayments
       #
       #   @param disputes [Array<Dodopayments::Models::Dispute>] List of disputes associated with this payment
       #
+      #   @param includes_usage [Boolean] True when this payment also bills metered usage or credit overage. The usage is
+      #
       #   @param is_multi_subscription [Boolean] True when one payment starts more than one subscription. Read this field
       #
       #   @param is_update_payment_method [Boolean] Whether this payment was created solely to update a subscription's
@@ -348,15 +391,21 @@ module Dodopayments
       #
       #   @param total_amount [Integer] Total amount charged to the customer including tax, in the currency's smallest u
       #
+      #   @param card_exp_month [String, nil] Expiry month of the card, as two digits from `01` to `12`. For Apple Pay and
+      #
+      #   @param card_exp_year [String, nil] Expiry year of the card, as four digits, for example `2029`. For Apple Pay and
+      #
       #   @param card_holder_name [String, nil] Cardholder name
       #
       #   @param card_issuing_country [Symbol, Dodopayments::Models::CountryCode, nil] ISO2 country code of the card
       #
       #   @param card_last_four [String, nil] The last four digits of the card
       #
-      #   @param card_network [String, nil] Card network like VISA, MASTERCARD etc.
+      #   @param card_network [String, nil] Card network, in lowercase, for example `visa`, `mastercard` or `amex`. Older pa
+      #
+      #   @param card_type [String, nil] The type of card, in lowercase: `credit`, `debit` or `prepaid`. Older payments c
       #
-      #   @param card_type [String, nil] The type of card DEBIT or CREDIT
+      #   @param charge_type [Symbol, Dodopayments::Models::ChargeType, nil] The type of subscription charge that this payment is for. Refer to `ChargeType`.
       #
       #   @param checkout_session_id [String, nil] If payment is made using a checkout session,
       #
@@ -372,7 +421,7 @@ module Dodopayments
       #
       #   @param invoice_id [String, nil] Invoice ID for this payment. Uses India-specific invoice ID if available.
       #
-      #   @param invoice_url [String, nil] URL to download the invoice PDF for this payment.
+      #   @param invoice_url [String, nil] DEPRECATED: Use `GET /invoices/payments/{payment_id}` with an API key.
       #
       #   @param payment_link [String, nil] Checkout URL
       #

data/lib/dodopayments/models/payment_list_response.rb

@@ -34,6 +34,14 @@ module Dodopayments
       #   @return [Boolean]
       required :has_license_key, Dodopayments::Internal::Type::Boolean
 
+      # @!attribute includes_usage
+      #   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.
+      #
+      #   @return [Boolean]
+      required :includes_usage, Dodopayments::Internal::Type::Boolean
+
       # @!attribute is_multi_subscription
       #   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
@@ -73,7 +81,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.
       #
       #   @return [Array<Dodopayments::Models::SubscriptionServicePeriod>]
       required :service_periods,
@@ -92,6 +103,22 @@ module Dodopayments
       #   @return [Integer]
       required :total_amount, Integer
 
+      # @!attribute card_exp_month
+      #   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.
+      #
+      #   @return [String, nil]
+      optional :card_exp_month, String, nil?: true
+
+      # @!attribute card_exp_year
+      #   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.
+      #
+      #   @return [String, nil]
+      optional :card_exp_year, String, nil?: true
+
       # @!attribute card_last_four
       #   The last four digits of the card
       #
@@ -99,11 +126,27 @@ module Dodopayments
       optional :card_last_four, String, nil?: true
 
       # @!attribute card_network
-      #   Card network like VISA, MASTERCARD etc.
+      #   Card network, in lowercase, for example `visa`, `mastercard` or `amex`. Older
+      #   payments can carry other casing.
       #
       #   @return [String, nil]
       optional :card_network, String, nil?: true
 
+      # @!attribute card_type
+      #   The type of card, in lowercase: `credit`, `debit` or `prepaid`. Older payments
+      #   can carry other casing.
+      #
+      #   @return [String, nil]
+      optional :card_type, String, nil?: true
+
+      # @!attribute charge_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.
+      #
+      #   @return [Symbol, Dodopayments::Models::ChargeType, nil]
+      optional :charge_type, enum: -> { Dodopayments::ChargeType }, nil?: true
+
       # @!attribute checkout_session_id
       #   The ID of the checkout session for this payment. The value is null when the
       #   payment does not use a checkout session.
@@ -124,7 +167,11 @@ module Dodopayments
       optional :invoice_id, String, nil?: true
 
       # @!attribute invoice_url
-      #   URL to download the invoice PDF for this payment.
+      #   @deprecated Use `GET /invoices/payments/{payment_id}` with an API key.
+      #
+      #   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.
       #
       #   @return [String, nil]
       optional :invoice_url, String, nil?: true
@@ -156,7 +203,7 @@ module Dodopayments
       #   @return [String, nil]
       optional :subscription_id, String, nil?: true
 
-      # @!method initialize(brand_id:, created_at:, currency:, customer:, digital_products_delivered:, has_license_key:, is_multi_subscription:, metadata:, payment_id:, payment_provider:, retry_attempt:, service_periods:, subscription_ids:, total_amount:, card_last_four: nil, card_network: nil, checkout_session_id: nil, dispute_status: nil, invoice_id: nil, invoice_url: nil, payment_method: nil, payment_method_type: nil, refund_status: nil, status: nil, subscription_id: nil)
+      # @!method initialize(brand_id:, created_at:, currency:, customer:, digital_products_delivered:, has_license_key:, includes_usage:, is_multi_subscription:, metadata:, payment_id:, payment_provider:, retry_attempt:, service_periods:, subscription_ids:, total_amount:, card_exp_month: nil, card_exp_year: nil, card_last_four: nil, card_network: nil, card_type: nil, charge_type: nil, checkout_session_id: nil, dispute_status: nil, invoice_id: nil, invoice_url: nil, payment_method: nil, payment_method_type: nil, refund_status: nil, status: nil, subscription_id: nil)
       #   Some parameter documentations has been truncated, see
       #   {Dodopayments::Models::PaymentListResponse} for more details.
       #
@@ -172,6 +219,8 @@ module Dodopayments
       #
       #   @param has_license_key [Boolean]
       #
+      #   @param includes_usage [Boolean] True when this payment also bills metered usage or credit overage. The usage is
+      #
       #   @param is_multi_subscription [Boolean] True when one payment starts more than one subscription. Read this field
       #
       #   @param metadata [Hash{Symbol=>String, Float, Boolean}] Arbitrary key-value metadata. Values can be string, integer, number, or boolean.
@@ -188,9 +237,17 @@ module Dodopayments
       #
       #   @param total_amount [Integer]
       #
+      #   @param card_exp_month [String, nil] Expiry month of the card, as two digits from `01` to `12`. For Apple Pay and
+      #
+      #   @param card_exp_year [String, nil] Expiry year of the card, as four digits, for example `2029`. For Apple Pay and
+      #
       #   @param card_last_four [String, nil] The last four digits of the card
       #
-      #   @param card_network [String, nil] Card network like VISA, MASTERCARD etc.
+      #   @param card_network [String, nil] Card network, in lowercase, for example `visa`, `mastercard` or `amex`. Older pa
+      #
+      #   @param card_type [String, nil] The type of card, in lowercase: `credit`, `debit` or `prepaid`. Older payments c
+      #
+      #   @param charge_type [Symbol, Dodopayments::Models::ChargeType, nil] The type of subscription charge that this payment is for. Refer to `ChargeType`.
       #
       #   @param checkout_session_id [String, nil] The ID of the checkout session for this payment. The value is null when
       #
@@ -198,7 +255,7 @@ module Dodopayments
       #
       #   @param invoice_id [String, nil] Invoice ID for this payment. Uses India-specific invoice ID if available.
       #
-      #   @param invoice_url [String, nil] URL to download the invoice PDF for this payment.
+      #   @param invoice_url [String, nil] DEPRECATED: Use `GET /invoices/payments/{payment_id}` with an API key.
       #
       #   @param payment_method [String, nil]
       #

data/lib/dodopayments/models/price.rb

@@ -122,14 +122,16 @@ module Dodopayments
         required :currency, enum: -> { Dodopayments::Currency }
 
         # @!attribute payment_frequency_count
-        #   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.
         #
         #   @return [Integer]
         required :payment_frequency_count, Integer
 
         # @!attribute payment_frequency_interval
-        #   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`.
         #
         #   @return [Symbol, Dodopayments::Models::TimeInterval]
         required :payment_frequency_interval, enum: -> { Dodopayments::TimeInterval }
@@ -142,14 +144,30 @@ module Dodopayments
         required :price, Integer
 
         # @!attribute subscription_period_count
-        #   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.
         #
         #   @return [Integer]
         required :subscription_period_count, Integer
 
         # @!attribute subscription_period_interval
-        #   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`.
         #
         #   @return [Symbol, Dodopayments::Models::TimeInterval]
         required :subscription_period_interval, enum: -> { Dodopayments::TimeInterval }
@@ -235,15 +253,15 @@ module Dodopayments
         #
         #   @param currency [Symbol, Dodopayments::Models::Currency] The currency in which the payment is made.
         #
-        #   @param payment_frequency_count [Integer] Number of units for the payment frequency.
+        #   @param payment_frequency_count [Integer] Number of `payment_frequency_interval` units between two charges.
         #
-        #   @param payment_frequency_interval [Symbol, Dodopayments::Models::TimeInterval] The time interval for the payment frequency (e.g., day, month, year).
+        #   @param payment_frequency_interval [Symbol, Dodopayments::Models::TimeInterval] The time unit of the billing cycle (e.g., day, month, year).
         #
         #   @param price [Integer] The payment amount. Represented in the lowest denomination of the currency (e.g.
         #
-        #   @param subscription_period_count [Integer] Number of units for the subscription period.
+        #   @param subscription_period_count [Integer] Number of `subscription_period_interval` units for the total duration of the sub
         #
-        #   @param subscription_period_interval [Symbol, Dodopayments::Models::TimeInterval] The time interval for the subscription period (e.g., day, month, year).
+        #   @param subscription_period_interval [Symbol, Dodopayments::Models::TimeInterval] The time unit of the total subscription duration (e.g., day, month, year).
         #
         #   @param discount [Integer] Deprecated: use `discount_bps` instead.
         #
@@ -281,27 +299,45 @@ module Dodopayments
         required :fixed_price, Integer
 
         # @!attribute payment_frequency_count
-        #   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.
         #
         #   @return [Integer]
         required :payment_frequency_count, Integer
 
         # @!attribute payment_frequency_interval
-        #   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`.
         #
         #   @return [Symbol, Dodopayments::Models::TimeInterval]
         required :payment_frequency_interval, enum: -> { Dodopayments::TimeInterval }
 
         # @!attribute subscription_period_count
-        #   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.
         #
         #   @return [Integer]
         required :subscription_period_count, Integer
 
         # @!attribute subscription_period_interval
-        #   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`.
         #
         #   @return [Symbol, Dodopayments::Models::TimeInterval]
         required :subscription_period_interval, enum: -> { Dodopayments::TimeInterval }
@@ -366,13 +402,13 @@ module Dodopayments
         #
         #   @param fixed_price [Integer] The fixed payment amount. Represented in the lowest denomination of the currency
         #
-        #   @param payment_frequency_count [Integer] Number of units for the payment frequency.
+        #   @param payment_frequency_count [Integer] Number of `payment_frequency_interval` units between two charges.
         #
-        #   @param payment_frequency_interval [Symbol, Dodopayments::Models::TimeInterval] The time interval for the payment frequency (e.g., day, month, year).
+        #   @param payment_frequency_interval [Symbol, Dodopayments::Models::TimeInterval] The time unit of the billing cycle (e.g., day, month, year).
         #
-        #   @param subscription_period_count [Integer] Number of units for the subscription period.
+        #   @param subscription_period_count [Integer] Number of `subscription_period_interval` units for the total duration of the sub
         #
-        #   @param subscription_period_interval [Symbol, Dodopayments::Models::TimeInterval] The time interval for the subscription period (e.g., day, month, year).
+        #   @param subscription_period_interval [Symbol, Dodopayments::Models::TimeInterval] The time unit of the total subscription duration (e.g., day, month, year).
         #
         #   @param discount [Integer] Deprecated: use `discount_bps` instead.
         #