dodopayments 1.51.0 → 1.52.4

data/lib/dodopayments/resources/meters.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Dodopayments
+  module Resources
+    class Meters
+      # @overload create(aggregation:, event_name:, measurement_unit:, name:, description: nil, filter: nil, request_options: {})
+      #
+      # @param aggregation [Dodopayments::Models::MeterAggregation] Aggregation configuration for the meter
+      #
+      # @param event_name [String] Event name to track
+      #
+      # @param measurement_unit [String] measurement unit
+      #
+      # @param name [String] Name of the meter
+      #
+      # @param description [String, nil] Optional description of the meter
+      #
+      # @param filter [Dodopayments::Models::MeterFilter, nil] Optional filter to apply to the meter
+      #
+      # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Dodopayments::Models::Meter]
+      #
+      # @see Dodopayments::Models::MeterCreateParams
+      def create(params)
+        parsed, options = Dodopayments::MeterCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "meters",
+          body: parsed,
+          model: Dodopayments::Meter,
+          options: options
+        )
+      end
+
+      # @overload retrieve(id, request_options: {})
+      #
+      # @param id [String] Meter ID
+      #
+      # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Dodopayments::Models::Meter]
+      #
+      # @see Dodopayments::Models::MeterRetrieveParams
+      def retrieve(id, params = {})
+        @client.request(
+          method: :get,
+          path: ["meters/%1$s", id],
+          model: Dodopayments::Meter,
+          options: params[:request_options]
+        )
+      end
+
+      # @overload list(archived: nil, page_number: nil, page_size: nil, request_options: {})
+      #
+      # @param archived [Boolean] List archived meters
+      #
+      # @param page_number [Integer] Page number default is 0
+      #
+      # @param page_size [Integer] Page size default is 10 max is 100
+      #
+      # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Dodopayments::Internal::DefaultPageNumberPagination<Dodopayments::Models::Meter>]
+      #
+      # @see Dodopayments::Models::MeterListParams
+      def list(params = {})
+        parsed, options = Dodopayments::MeterListParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: "meters",
+          query: parsed,
+          page: Dodopayments::Internal::DefaultPageNumberPagination,
+          model: Dodopayments::Meter,
+          options: options
+        )
+      end
+
+      # @overload archive(id, request_options: {})
+      #
+      # @param id [String] Meter ID
+      #
+      # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [nil]
+      #
+      # @see Dodopayments::Models::MeterArchiveParams
+      def archive(id, params = {})
+        @client.request(
+          method: :delete,
+          path: ["meters/%1$s", id],
+          model: NilClass,
+          options: params[:request_options]
+        )
+      end
+
+      # @overload unarchive(id, request_options: {})
+      #
+      # @param id [String] Meter ID
+      #
+      # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [nil]
+      #
+      # @see Dodopayments::Models::MeterUnarchiveParams
+      def unarchive(id, params = {})
+        @client.request(
+          method: :post,
+          path: ["meters/%1$s/unarchive", id],
+          model: NilClass,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Dodopayments::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/dodopayments/resources/products.rb

@@ -11,7 +11,7 @@ module Dodopayments
       #
       # @overload create(price:, tax_category:, addons: nil, brand_id: nil, description: nil, digital_product_delivery: nil, license_key_activation_message: nil, license_key_activations_limit: nil, license_key_duration: nil, license_key_enabled: nil, metadata: nil, name: nil, request_options: {})
       #
-      # @param price [Dodopayments::Models::Price::OneTimePrice, Dodopayments::Models::Price::RecurringPrice] Price configuration for the product
+      # @param price [Dodopayments::Models::Price::OneTimePrice, Dodopayments::Models::Price::RecurringPrice, Dodopayments::Models::Price::UsageBasedPrice] Price configuration for the product
       #
       # @param tax_category [Symbol, Dodopayments::Models::TaxCategory] Tax category applied to this product
       #
@@ -98,7 +98,7 @@ module Dodopayments
       #
       # @param name [String, nil] Name of the product, optional and must be at most 100 characters.
       #
-      # @param price [Dodopayments::Models::Price::OneTimePrice, Dodopayments::Models::Price::RecurringPrice, nil] Price details of the product.
+      # @param price [Dodopayments::Models::Price::OneTimePrice, Dodopayments::Models::Price::RecurringPrice, Dodopayments::Models::Price::UsageBasedPrice, nil] Price details of the product.
       #
       # @param tax_category [Symbol, Dodopayments::Models::TaxCategory, nil] Tax category of the product.
       #
@@ -150,15 +150,15 @@ module Dodopayments
         )
       end
 
-      # @overload delete(id, request_options: {})
+      # @overload archive(id, request_options: {})
       #
       # @param id [String]
       # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [nil]
       #
-      # @see Dodopayments::Models::ProductDeleteParams
-      def delete(id, params = {})
+      # @see Dodopayments::Models::ProductArchiveParams
+      def archive(id, params = {})
         @client.request(
           method: :delete,
           path: ["products/%1$s", id],

data/lib/dodopayments/resources/subscriptions.rb

@@ -203,6 +203,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)
+      #
+      # @overload retrieve_usage_history(subscription_id, end_date: nil, meter_id: nil, page_number: nil, page_size: nil, start_date: nil, request_options: {})
+      #
+      # @param subscription_id [String] Unique subscription identifier
+      #
+      # @param end_date [Time, nil] Filter by end date (inclusive)
+      #
+      # @param meter_id [String, nil] Filter by specific meter ID
+      #
+      # @param page_number [Integer, nil] Page number (default: 0)
+      #
+      # @param page_size [Integer, nil] Page size (default: 10, max: 100)
+      #
+      # @param start_date [Time, nil] Filter by start date (inclusive)
+      #
+      # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Dodopayments::Internal::DefaultPageNumberPagination<Dodopayments::Models::SubscriptionRetrieveUsageHistoryResponse>]
+      #
+      # @see Dodopayments::Models::SubscriptionRetrieveUsageHistoryParams
+      def retrieve_usage_history(subscription_id, params = {})
+        parsed, options = Dodopayments::SubscriptionRetrieveUsageHistoryParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: ["subscriptions/%1$s/usage-history", subscription_id],
+          query: parsed,
+          page: Dodopayments::Internal::DefaultPageNumberPagination,
+          model: Dodopayments::Models::SubscriptionRetrieveUsageHistoryResponse,
+          options: options
+        )
+      end
+
       # @api private
       #
       # @param client [Dodopayments::Client]

data/lib/dodopayments/resources/usage_events.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Dodopayments
+  module Resources
+    class UsageEvents
+      # Some parameter documentations has been truncated, see
+      # {Dodopayments::Models::UsageEventRetrieveParams} for more details.
+      #
+      # 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
+      # ```
+      #
+      # @overload retrieve(event_id, request_options: {})
+      #
+      # @param event_id [String] Unique event identifier (case-sensitive, must match the ID used during ingestion
+      #
+      # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Dodopayments::Models::Event]
+      #
+      # @see Dodopayments::Models::UsageEventRetrieveParams
+      def retrieve(event_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["events/%1$s", event_id],
+          model: Dodopayments::Event,
+          options: params[:request_options]
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Dodopayments::Models::UsageEventListParams} for more details.
+      #
+      # 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`
+      #
+      # @overload list(customer_id: nil, end_: nil, event_name: nil, meter_id: nil, page_number: nil, page_size: nil, start: nil, request_options: {})
+      #
+      # @param customer_id [String] Filter events by customer ID
+      #
+      # @param end_ [Time] Filter events created before this timestamp
+      #
+      # @param event_name [String] Filter events by event name. If both event_name and meter_id are provided, they
+      #
+      # @param meter_id [String] Filter events by meter ID. When provided, only events that match the meter's eve
+      #
+      # @param page_number [Integer] Page number (0-based, default: 0)
+      #
+      # @param page_size [Integer] Number of events to return per page (default: 10)
+      #
+      # @param start [Time] Filter events created after this timestamp
+      #
+      # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Dodopayments::Internal::DefaultPageNumberPagination<Dodopayments::Models::Event>]
+      #
+      # @see Dodopayments::Models::UsageEventListParams
+      def list(params = {})
+        parsed, options = Dodopayments::UsageEventListParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: "events",
+          query: parsed.transform_keys(end_: "end"),
+          page: Dodopayments::Internal::DefaultPageNumberPagination,
+          model: Dodopayments::Event,
+          options: 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"
+      #       }
+      #     }
+      #   ]
+      # }
+      # ```
+      #
+      # @overload ingest(events:, request_options: {})
+      #
+      # @param events [Array<Dodopayments::Models::EventInput>] List of events to be pushed
+      #
+      # @param request_options [Dodopayments::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Dodopayments::Models::UsageEventIngestResponse]
+      #
+      # @see Dodopayments::Models::UsageEventIngestParams
+      def ingest(params)
+        parsed, options = Dodopayments::UsageEventIngestParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "events/ingest",
+          body: parsed,
+          model: Dodopayments::Models::UsageEventIngestResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Dodopayments::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/dodopayments/version.rb

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

data/lib/dodopayments.rb

@@ -58,6 +58,7 @@ require_relative "dodopayments/models/get_dispute"
 require_relative "dodopayments/models/refund"
 require_relative "dodopayments/models/subscription"
 require_relative "dodopayments/models/payment"
+require_relative "dodopayments/models/add_meter_to_price"
 require_relative "dodopayments/models/addon_cart_response_item"
 require_relative "dodopayments/models/addon_create_params"
 require_relative "dodopayments/models/addon_list_params"
@@ -104,8 +105,11 @@ require_relative "dodopayments/models/dispute_list_response"
 require_relative "dodopayments/models/dispute_retrieve_params"
 require_relative "dodopayments/models/dispute_stage"
 require_relative "dodopayments/models/dispute_status"
+require_relative "dodopayments/models/event"
+require_relative "dodopayments/models/event_input"
 require_relative "dodopayments/models/intent_status"
 require_relative "dodopayments/models/invoices/payment_retrieve_params"
+require_relative "dodopayments/models/invoices/payment_retrieve_refund_params"
 require_relative "dodopayments/models/license_activate_params"
 require_relative "dodopayments/models/license_deactivate_params"
 require_relative "dodopayments/models/license_key_duration"
@@ -119,6 +123,14 @@ require_relative "dodopayments/models/license_key_status"
 require_relative "dodopayments/models/license_key_update_params"
 require_relative "dodopayments/models/license_validate_params"
 require_relative "dodopayments/models/license_validate_response"
+require_relative "dodopayments/models/meter"
+require_relative "dodopayments/models/meter_aggregation"
+require_relative "dodopayments/models/meter_archive_params"
+require_relative "dodopayments/models/meter_create_params"
+require_relative "dodopayments/models/meter_filter"
+require_relative "dodopayments/models/meter_list_params"
+require_relative "dodopayments/models/meter_retrieve_params"
+require_relative "dodopayments/models/meter_unarchive_params"
 require_relative "dodopayments/models/misc_list_supported_countries_params"
 require_relative "dodopayments/models/misc_list_supported_countries_response"
 require_relative "dodopayments/models/new_customer"
@@ -136,8 +148,8 @@ require_relative "dodopayments/models/payout_list_params"
 require_relative "dodopayments/models/payout_list_response"
 require_relative "dodopayments/models/price"
 require_relative "dodopayments/models/product"
+require_relative "dodopayments/models/product_archive_params"
 require_relative "dodopayments/models/product_create_params"
-require_relative "dodopayments/models/product_delete_params"
 require_relative "dodopayments/models/product_list_params"
 require_relative "dodopayments/models/product_list_response"
 require_relative "dodopayments/models/product_retrieve_params"
@@ -159,10 +171,16 @@ require_relative "dodopayments/models/subscription_create_response"
 require_relative "dodopayments/models/subscription_list_params"
 require_relative "dodopayments/models/subscription_list_response"
 require_relative "dodopayments/models/subscription_retrieve_params"
+require_relative "dodopayments/models/subscription_retrieve_usage_history_params"
+require_relative "dodopayments/models/subscription_retrieve_usage_history_response"
 require_relative "dodopayments/models/subscription_status"
 require_relative "dodopayments/models/subscription_update_params"
 require_relative "dodopayments/models/tax_category"
 require_relative "dodopayments/models/time_interval"
+require_relative "dodopayments/models/usage_event_ingest_params"
+require_relative "dodopayments/models/usage_event_ingest_response"
+require_relative "dodopayments/models/usage_event_list_params"
+require_relative "dodopayments/models/usage_event_retrieve_params"
 require_relative "dodopayments/models/webhook_create_params"
 require_relative "dodopayments/models/webhook_delete_params"
 require_relative "dodopayments/models/webhook_details"
@@ -189,6 +207,7 @@ require_relative "dodopayments/resources/invoices/payments"
 require_relative "dodopayments/resources/license_key_instances"
 require_relative "dodopayments/resources/license_keys"
 require_relative "dodopayments/resources/licenses"
+require_relative "dodopayments/resources/meters"
 require_relative "dodopayments/resources/misc"
 require_relative "dodopayments/resources/payments"
 require_relative "dodopayments/resources/payouts"
@@ -196,6 +215,7 @@ require_relative "dodopayments/resources/products"
 require_relative "dodopayments/resources/products/images"
 require_relative "dodopayments/resources/refunds"
 require_relative "dodopayments/resources/subscriptions"
+require_relative "dodopayments/resources/usage_events"
 require_relative "dodopayments/resources/webhook_events"
 require_relative "dodopayments/resources/webhooks"
 require_relative "dodopayments/resources/webhooks/headers"

data/rbi/dodopayments/client.rbi

@@ -77,6 +77,12 @@ module Dodopayments
     sig { returns(Dodopayments::Resources::Webhooks) }
     attr_reader :webhooks
 
+    sig { returns(Dodopayments::Resources::UsageEvents) }
+    attr_reader :usage_events
+
+    sig { returns(Dodopayments::Resources::Meters) }
+    attr_reader :meters
+
     # @api private
     sig { override.returns(T::Hash[String, String]) }
     private def auth_headers

data/rbi/dodopayments/models/add_meter_to_price.rbi

@@ -0,0 +1,75 @@
+# typed: strong
+
+module Dodopayments
+  module Models
+    class AddMeterToPrice < Dodopayments::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Dodopayments::AddMeterToPrice, Dodopayments::Internal::AnyHash)
+        end
+
+      sig { returns(String) }
+      attr_accessor :meter_id
+
+      # The price per unit in lowest denomination. Must be greater than zero. Supports
+      # up to 5 digits before decimal point and 12 decimal places.
+      sig { returns(String) }
+      attr_accessor :price_per_unit
+
+      # Meter description. Will ignored on Request, but will be shown in response
+      sig { returns(T.nilable(String)) }
+      attr_accessor :description
+
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :free_threshold
+
+      # Meter measurement unit. Will ignored on Request, but will be shown in response
+      sig { returns(T.nilable(String)) }
+      attr_accessor :measurement_unit
+
+      # Meter name. Will ignored on Request, but will be shown in response
+      sig { returns(T.nilable(String)) }
+      attr_accessor :name
+
+      sig do
+        params(
+          meter_id: String,
+          price_per_unit: String,
+          description: T.nilable(String),
+          free_threshold: T.nilable(Integer),
+          measurement_unit: T.nilable(String),
+          name: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        meter_id:,
+        # The price per unit in lowest denomination. Must be greater than zero. Supports
+        # up to 5 digits before decimal point and 12 decimal places.
+        price_per_unit:,
+        # Meter description. Will ignored on Request, but will be shown in response
+        description: nil,
+        free_threshold: nil,
+        # Meter measurement unit. Will ignored on Request, but will be shown in response
+        measurement_unit: nil,
+        # Meter name. Will ignored on Request, but will be shown in response
+        name: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            meter_id: String,
+            price_per_unit: String,
+            description: T.nilable(String),
+            free_threshold: T.nilable(Integer),
+            measurement_unit: T.nilable(String),
+            name: T.nilable(String)
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end