dodopayments 1.51.1 → 1.52.4

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:)

data/rbi/dodopayments/resources/usage_events.rbi

@@ -0,0 +1,175 @@
+# typed: strong
+
+module Dodopayments
+  module Resources
+    class UsageEvents
+      # Fetch detailed information about a single event using its unique event ID. This
+      # endpoint is useful for:
+      #
+      # - Debugging specific event ingestion issues
+      # - Retrieving event details for customer support
+      # - Validating that events were processed correctly
+      # - Getting the complete metadata for an event
+      #
+      # ## Event ID Format:
+      #
+      # The event ID should be the same value that was provided during event ingestion
+      # via the `/events/ingest` endpoint. Event IDs are case-sensitive and must match
+      # exactly.
+      #
+      # ## Response Details:
+      #
+      # The response includes all event data including:
+      #
+      # - Complete metadata key-value pairs
+      # - Original timestamp (preserved from ingestion)
+      # - Customer and business association
+      # - Event name and processing information
+      #
+      # ## Example Usage:
+      #
+      # ```text
+      # GET /events/api_call_12345
+      # ```
+      sig do
+        params(
+          event_id: String,
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).returns(Dodopayments::Event)
+      end
+      def retrieve(
+        # Unique event identifier (case-sensitive, must match the ID used during
+        # ingestion)
+        event_id,
+        request_options: {}
+      )
+      end
+
+      # Fetch events from your account with powerful filtering capabilities. This
+      # endpoint is ideal for:
+      #
+      # - Debugging event ingestion issues
+      # - Analyzing customer usage patterns
+      # - Building custom analytics dashboards
+      # - Auditing billing-related events
+      #
+      # ## Filtering Options:
+      #
+      # - **Customer filtering**: Filter by specific customer ID
+      # - **Event name filtering**: Filter by event type/name
+      # - **Meter-based filtering**: Use a meter ID to apply the meter's event name and
+      #   filter criteria automatically
+      # - **Time range filtering**: Filter events within a specific date range
+      # - **Pagination**: Navigate through large result sets
+      #
+      # ## Meter Integration:
+      #
+      # When using `meter_id`, the endpoint automatically applies:
+      #
+      # - The meter's configured `event_name` filter
+      # - The meter's custom filter criteria (if any)
+      # - If you also provide `event_name`, it must match the meter's event name
+      #
+      # ## Example Queries:
+      #
+      # - Get all events for a customer: `?customer_id=cus_abc123`
+      # - Get API request events: `?event_name=api_request`
+      # - Get events from last 24 hours:
+      #   `?start=2024-01-14T10:30:00Z&end=2024-01-15T10:30:00Z`
+      # - Get events with meter filtering: `?meter_id=mtr_xyz789`
+      # - Paginate results: `?page_size=50&page_number=2`
+      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(
+          Dodopayments::Internal::DefaultPageNumberPagination[
+            Dodopayments::Event
+          ]
+        )
+      end
+      def list(
+        # 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
+
+      # This endpoint allows you to ingest custom events that can be used for:
+      #
+      # - Usage-based billing and metering
+      # - Analytics and reporting
+      # - Customer behavior tracking
+      #
+      # ## Important Notes:
+      #
+      # - **Duplicate Prevention**:
+      #   - Duplicate `event_id` values within the same request are rejected (entire
+      #     request fails)
+      #   - Subsequent requests with existing `event_id` values are ignored (idempotent
+      #     behavior)
+      # - **Rate Limiting**: Maximum 1000 events per request
+      # - **Time Validation**: Events with timestamps older than 1 hour or more than 5
+      #   minutes in the future will be rejected
+      # - **Metadata Limits**: Maximum 50 key-value pairs per event, keys max 100 chars,
+      #   values max 500 chars
+      #
+      # ## Example Usage:
+      #
+      # ```json
+      # {
+      #   "events": [
+      #     {
+      #       "event_id": "api_call_12345",
+      #       "customer_id": "cus_abc123",
+      #       "event_name": "api_request",
+      #       "timestamp": "2024-01-15T10:30:00Z",
+      #       "metadata": {
+      #         "endpoint": "/api/v1/users",
+      #         "method": "GET",
+      #         "tokens_used": "150"
+      #       }
+      #     }
+      #   ]
+      # }
+      # ```
+      sig do
+        params(
+          events: T::Array[Dodopayments::EventInput::OrHash],
+          request_options: Dodopayments::RequestOptions::OrHash
+        ).returns(Dodopayments::Models::UsageEventIngestResponse)
+      end
+      def ingest(
+        # List of events to be pushed
+        events:,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Dodopayments::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end