dodopayments 1.51.1 → 1.52.5

data/rbi/dodopayments/models/subscription_retrieve_usage_history_response.rbi

@@ -0,0 +1,159 @@
+# typed: strong
+
+module Dodopayments
+  module Models
+    class SubscriptionRetrieveUsageHistoryResponse < Dodopayments::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Dodopayments::Models::SubscriptionRetrieveUsageHistoryResponse,
+            Dodopayments::Internal::AnyHash
+          )
+        end
+
+      # End date of the billing period
+      sig { returns(Time) }
+      attr_accessor :end_date
+
+      # List of meters and their usage for this billing period
+      sig do
+        returns(
+          T::Array[
+            Dodopayments::Models::SubscriptionRetrieveUsageHistoryResponse::Meter
+          ]
+        )
+      end
+      attr_accessor :meters
+
+      # Start date of the billing period
+      sig { returns(Time) }
+      attr_accessor :start_date
+
+      sig do
+        params(
+          end_date: Time,
+          meters:
+            T::Array[
+              Dodopayments::Models::SubscriptionRetrieveUsageHistoryResponse::Meter::OrHash
+            ],
+          start_date: Time
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # End date of the billing period
+        end_date:,
+        # List of meters and their usage for this billing period
+        meters:,
+        # Start date of the billing period
+        start_date:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            end_date: Time,
+            meters:
+              T::Array[
+                Dodopayments::Models::SubscriptionRetrieveUsageHistoryResponse::Meter
+              ],
+            start_date: Time
+          }
+        )
+      end
+      def to_hash
+      end
+
+      class Meter < Dodopayments::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Dodopayments::Models::SubscriptionRetrieveUsageHistoryResponse::Meter,
+              Dodopayments::Internal::AnyHash
+            )
+          end
+
+        # Meter identifier
+        sig { returns(String) }
+        attr_accessor :id
+
+        # Chargeable units (after free threshold) as string for precision
+        sig { returns(String) }
+        attr_accessor :chargeable_units
+
+        # Total units consumed as string for precision
+        sig { returns(String) }
+        attr_accessor :consumed_units
+
+        # Currency for the price per unit
+        sig { returns(Dodopayments::Currency::TaggedSymbol) }
+        attr_accessor :currency
+
+        # Free threshold units for this meter
+        sig { returns(Integer) }
+        attr_accessor :free_threshold
+
+        # Meter name
+        sig { returns(String) }
+        attr_accessor :name
+
+        # Price per unit in string format for precision
+        sig { returns(String) }
+        attr_accessor :price_per_unit
+
+        # Total price charged for this meter in smallest currency unit (cents)
+        sig { returns(Integer) }
+        attr_accessor :total_price
+
+        sig do
+          params(
+            id: String,
+            chargeable_units: String,
+            consumed_units: String,
+            currency: Dodopayments::Currency::OrSymbol,
+            free_threshold: Integer,
+            name: String,
+            price_per_unit: String,
+            total_price: Integer
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Meter identifier
+          id:,
+          # Chargeable units (after free threshold) as string for precision
+          chargeable_units:,
+          # Total units consumed as string for precision
+          consumed_units:,
+          # Currency for the price per unit
+          currency:,
+          # Free threshold units for this meter
+          free_threshold:,
+          # Meter name
+          name:,
+          # Price per unit in string format for precision
+          price_per_unit:,
+          # Total price charged for this meter in smallest currency unit (cents)
+          total_price:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              id: String,
+              chargeable_units: String,
+              consumed_units: String,
+              currency: Dodopayments::Currency::TaggedSymbol,
+              free_threshold: Integer,
+              name: String,
+              price_per_unit: String,
+              total_price: Integer
+            }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/dodopayments/models/usage_event_ingest_params.rbi

@@ -0,0 +1,46 @@
+# typed: strong
+
+module Dodopayments
+  module Models
+    class UsageEventIngestParams < Dodopayments::Internal::Type::BaseModel
+      extend Dodopayments::Internal::Type::RequestParameters::Converter
+      include Dodopayments::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            Dodopayments::UsageEventIngestParams,
+            Dodopayments::Internal::AnyHash
+          )
+        end
+
+      # List of events to be pushed
+      sig { returns(T::Array[Dodopayments::EventInput]) }
+      attr_accessor :events
+
+      sig do
+        params(
+          events: T::Array[Dodopayments::EventInput::OrHash],
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # List of events to be pushed
+        events:,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            events: T::Array[Dodopayments::EventInput],
+            request_options: Dodopayments::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/dodopayments/models/usage_event_ingest_response.rbi

@@ -0,0 +1,26 @@
+# typed: strong
+
+module Dodopayments
+  module Models
+    class UsageEventIngestResponse < Dodopayments::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Dodopayments::Models::UsageEventIngestResponse,
+            Dodopayments::Internal::AnyHash
+          )
+        end
+
+      sig { returns(Integer) }
+      attr_accessor :ingested_count
+
+      sig { params(ingested_count: Integer).returns(T.attached_class) }
+      def self.new(ingested_count:)
+      end
+
+      sig { override.returns({ ingested_count: Integer }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/dodopayments/models/usage_event_list_params.rbi

@@ -0,0 +1,119 @@
+# typed: strong
+
+module Dodopayments
+  module Models
+    class UsageEventListParams < Dodopayments::Internal::Type::BaseModel
+      extend Dodopayments::Internal::Type::RequestParameters::Converter
+      include Dodopayments::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            Dodopayments::UsageEventListParams,
+            Dodopayments::Internal::AnyHash
+          )
+        end
+
+      # Filter events by customer ID
+      sig { returns(T.nilable(String)) }
+      attr_reader :customer_id
+
+      sig { params(customer_id: String).void }
+      attr_writer :customer_id
+
+      # Filter events created before this timestamp
+      sig { returns(T.nilable(Time)) }
+      attr_reader :end_
+
+      sig { params(end_: Time).void }
+      attr_writer :end_
+
+      # Filter events by event name. If both event_name and meter_id are provided, they
+      # must match the meter's configured event_name
+      sig { returns(T.nilable(String)) }
+      attr_reader :event_name
+
+      sig { params(event_name: String).void }
+      attr_writer :event_name
+
+      # Filter events by meter ID. When provided, only events that match the meter's
+      # event_name and filter criteria will be returned
+      sig { returns(T.nilable(String)) }
+      attr_reader :meter_id
+
+      sig { params(meter_id: String).void }
+      attr_writer :meter_id
+
+      # Page number (0-based, default: 0)
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :page_number
+
+      sig { params(page_number: Integer).void }
+      attr_writer :page_number
+
+      # Number of events to return per page (default: 10)
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :page_size
+
+      sig { params(page_size: Integer).void }
+      attr_writer :page_size
+
+      # Filter events created after this timestamp
+      sig { returns(T.nilable(Time)) }
+      attr_reader :start
+
+      sig { params(start: Time).void }
+      attr_writer :start
+
+      sig do
+        params(
+          customer_id: String,
+          end_: Time,
+          event_name: String,
+          meter_id: String,
+          page_number: Integer,
+          page_size: Integer,
+          start: Time,
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Filter events by customer ID
+        customer_id: nil,
+        # Filter events created before this timestamp
+        end_: nil,
+        # Filter events by event name. If both event_name and meter_id are provided, they
+        # must match the meter's configured event_name
+        event_name: nil,
+        # Filter events by meter ID. When provided, only events that match the meter's
+        # event_name and filter criteria will be returned
+        meter_id: nil,
+        # Page number (0-based, default: 0)
+        page_number: nil,
+        # Number of events to return per page (default: 10)
+        page_size: nil,
+        # Filter events created after this timestamp
+        start: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            customer_id: String,
+            end_: Time,
+            event_name: String,
+            meter_id: String,
+            page_number: Integer,
+            page_size: Integer,
+            start: Time,
+            request_options: Dodopayments::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/dodopayments/models/usage_event_retrieve_params.rbi

@@ -0,0 +1,32 @@
+# typed: strong
+
+module Dodopayments
+  module Models
+    class UsageEventRetrieveParams < Dodopayments::Internal::Type::BaseModel
+      extend Dodopayments::Internal::Type::RequestParameters::Converter
+      include Dodopayments::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            Dodopayments::UsageEventRetrieveParams,
+            Dodopayments::Internal::AnyHash
+          )
+        end
+
+      sig do
+        params(request_options: Dodopayments::RequestOptions::OrHash).returns(
+          T.attached_class
+        )
+      end
+      def self.new(request_options: {})
+      end
+
+      sig do
+        override.returns({ request_options: Dodopayments::RequestOptions })
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/dodopayments/models.rbi

@@ -1,6 +1,8 @@
 # typed: strong
 
 module Dodopayments
+  AddMeterToPrice = Dodopayments::Models::AddMeterToPrice
+
   AddonCartResponseItem = Dodopayments::Models::AddonCartResponseItem
 
   AddonCreateParams = Dodopayments::Models::AddonCreateParams
@@ -88,6 +90,10 @@ module Dodopayments
 
   DisputeStatus = Dodopayments::Models::DisputeStatus
 
+  Event = Dodopayments::Models::Event
+
+  EventInput = Dodopayments::Models::EventInput
+
   GetDispute = Dodopayments::Models::GetDispute
 
   IntentStatus = Dodopayments::Models::IntentStatus
@@ -123,6 +129,22 @@ module Dodopayments
 
   LicenseValidateParams = Dodopayments::Models::LicenseValidateParams
 
+  Meter = Dodopayments::Models::Meter
+
+  MeterAggregation = Dodopayments::Models::MeterAggregation
+
+  MeterArchiveParams = Dodopayments::Models::MeterArchiveParams
+
+  MeterCreateParams = Dodopayments::Models::MeterCreateParams
+
+  MeterFilter = Dodopayments::Models::MeterFilter
+
+  MeterListParams = Dodopayments::Models::MeterListParams
+
+  MeterRetrieveParams = Dodopayments::Models::MeterRetrieveParams
+
+  MeterUnarchiveParams = Dodopayments::Models::MeterUnarchiveParams
+
   MiscListSupportedCountriesParams =
     Dodopayments::Models::MiscListSupportedCountriesParams
 
@@ -151,9 +173,9 @@ module Dodopayments
 
   Product = Dodopayments::Models::Product
 
-  ProductCreateParams = Dodopayments::Models::ProductCreateParams
+  ProductArchiveParams = Dodopayments::Models::ProductArchiveParams
 
-  ProductDeleteParams = Dodopayments::Models::ProductDeleteParams
+  ProductCreateParams = Dodopayments::Models::ProductCreateParams
 
   ProductListParams = Dodopayments::Models::ProductListParams
 
@@ -190,6 +212,9 @@ module Dodopayments
 
   SubscriptionRetrieveParams = Dodopayments::Models::SubscriptionRetrieveParams
 
+  SubscriptionRetrieveUsageHistoryParams =
+    Dodopayments::Models::SubscriptionRetrieveUsageHistoryParams
+
   SubscriptionStatus = Dodopayments::Models::SubscriptionStatus
 
   SubscriptionUpdateParams = Dodopayments::Models::SubscriptionUpdateParams
@@ -198,6 +223,12 @@ module Dodopayments
 
   TimeInterval = Dodopayments::Models::TimeInterval
 
+  UsageEventIngestParams = Dodopayments::Models::UsageEventIngestParams
+
+  UsageEventListParams = Dodopayments::Models::UsageEventListParams
+
+  UsageEventRetrieveParams = Dodopayments::Models::UsageEventRetrieveParams
+
   WebhookCreateParams = Dodopayments::Models::WebhookCreateParams
 
   WebhookDeleteParams = Dodopayments::Models::WebhookDeleteParams

data/rbi/dodopayments/resources/invoices/payments.rbi

@@ -13,6 +13,15 @@ module Dodopayments
         def retrieve(payment_id, request_options: {})
         end
 
+        sig do
+          params(
+            refund_id: String,
+            request_options: Dodopayments::RequestOptions::OrHash
+          ).returns(StringIO)
+        end
+        def retrieve_refund(refund_id, request_options: {})
+        end
+
         # @api private
         sig { params(client: Dodopayments::Client).returns(T.attached_class) }
         def self.new(client:)

data/rbi/dodopayments/resources/meters.rbi

@@ -0,0 +1,102 @@
+# typed: strong
+
+module Dodopayments
+  module Resources
+    class Meters
+      sig do
+        params(
+          aggregation: Dodopayments::MeterAggregation::OrHash,
+          event_name: String,
+          measurement_unit: String,
+          name: String,
+          description: T.nilable(String),
+          filter: T.nilable(Dodopayments::MeterFilter::OrHash),
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).returns(Dodopayments::Meter)
+      end
+      def create(
+        # Aggregation configuration for the meter
+        aggregation:,
+        # Event name to track
+        event_name:,
+        # measurement unit
+        measurement_unit:,
+        # Name of the meter
+        name:,
+        # Optional description of the meter
+        description: nil,
+        # Optional filter to apply to the meter
+        filter: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        params(
+          id: String,
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).returns(Dodopayments::Meter)
+      end
+      def retrieve(
+        # Meter ID
+        id,
+        request_options: {}
+      )
+      end
+
+      sig do
+        params(
+          archived: T::Boolean,
+          page_number: Integer,
+          page_size: Integer,
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).returns(
+          Dodopayments::Internal::DefaultPageNumberPagination[
+            Dodopayments::Meter
+          ]
+        )
+      end
+      def list(
+        # List archived meters
+        archived: nil,
+        # Page number default is 0
+        page_number: nil,
+        # Page size default is 10 max is 100
+        page_size: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        params(
+          id: String,
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).void
+      end
+      def archive(
+        # Meter ID
+        id,
+        request_options: {}
+      )
+      end
+
+      sig do
+        params(
+          id: String,
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).void
+      end
+      def unarchive(
+        # Meter ID
+        id,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Dodopayments::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/dodopayments/resources/products.rbi

@@ -11,7 +11,8 @@ module Dodopayments
           price:
             T.any(
               Dodopayments::Price::OneTimePrice::OrHash,
-              Dodopayments::Price::RecurringPrice::OrHash
+              Dodopayments::Price::RecurringPrice::OrHash,
+              Dodopayments::Price::UsageBasedPrice::OrHash
             ),
           tax_category: Dodopayments::TaxCategory::OrSymbol,
           addons: T.nilable(T::Array[String]),
@@ -97,7 +98,8 @@ module Dodopayments
             T.nilable(
               T.any(
                 Dodopayments::Price::OneTimePrice::OrHash,
-                Dodopayments::Price::RecurringPrice::OrHash
+                Dodopayments::Price::RecurringPrice::OrHash,
+                Dodopayments::Price::UsageBasedPrice::OrHash
               )
             ),
           tax_category: T.nilable(Dodopayments::TaxCategory::OrSymbol),
@@ -186,7 +188,7 @@ module Dodopayments
           request_options: Dodopayments::RequestOptions::OrHash
         ).void
       end
-      def delete(id, request_options: {})
+      def archive(id, request_options: {})
       end
 
       sig do

data/rbi/dodopayments/resources/subscriptions.rbi

@@ -210,6 +210,80 @@ module Dodopayments
       )
       end
 
+      # Get detailed usage history for a subscription that includes usage-based billing
+      # (metered components). This endpoint provides insights into customer usage
+      # patterns and billing calculations over time.
+      #
+      # ## What You'll Get:
+      #
+      # - **Billing periods**: Each item represents a billing cycle with start and end
+      #   dates
+      # - **Meter usage**: Detailed breakdown of usage for each meter configured on the
+      #   subscription
+      # - **Usage calculations**: Total units consumed, free threshold units, and
+      #   chargeable units
+      # - **Historical tracking**: Complete audit trail of usage-based charges
+      #
+      # ## Use Cases:
+      #
+      # - **Customer support**: Investigate billing questions and usage discrepancies
+      # - **Usage analytics**: Analyze customer consumption patterns over time
+      # - **Billing transparency**: Provide customers with detailed usage breakdowns
+      # - **Revenue optimization**: Identify usage trends to optimize pricing strategies
+      #
+      # ## Filtering Options:
+      #
+      # - **Date range filtering**: Get usage history for specific time periods
+      # - **Meter-specific filtering**: Focus on usage for a particular meter
+      # - **Pagination**: Navigate through large usage histories efficiently
+      #
+      # ## Important Notes:
+      #
+      # - Only returns data for subscriptions with usage-based (metered) components
+      # - Usage history is organized by billing periods (subscription cycles)
+      # - Free threshold units are calculated and displayed separately from chargeable
+      #   units
+      # - Historical data is preserved even if meter configurations change
+      #
+      # ## Example Query Patterns:
+      #
+      # - Get last 3 months:
+      #   `?start_date=2024-01-01T00:00:00Z&end_date=2024-03-31T23:59:59Z`
+      # - Filter by meter: `?meter_id=mtr_api_requests`
+      # - Paginate results: `?page_size=20&page_number=1`
+      # - Recent usage: `?start_date=2024-03-01T00:00:00Z` (from March 1st to now)
+      sig do
+        params(
+          subscription_id: String,
+          end_date: T.nilable(Time),
+          meter_id: T.nilable(String),
+          page_number: T.nilable(Integer),
+          page_size: T.nilable(Integer),
+          start_date: T.nilable(Time),
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).returns(
+          Dodopayments::Internal::DefaultPageNumberPagination[
+            Dodopayments::Models::SubscriptionRetrieveUsageHistoryResponse
+          ]
+        )
+      end
+      def retrieve_usage_history(
+        # Unique subscription identifier
+        subscription_id,
+        # Filter by end date (inclusive)
+        end_date: nil,
+        # Filter by specific meter ID
+        meter_id: nil,
+        # Page number (default: 0)
+        page_number: nil,
+        # Page size (default: 10, max: 100)
+        page_size: nil,
+        # Filter by start date (inclusive)
+        start_date: nil,
+        request_options: {}
+      )
+      end
+
       # @api private
       sig { params(client: Dodopayments::Client).returns(T.attached_class) }
       def self.new(client:)