usage_credits 0.1.1 → 0.2.0

data/lib/usage_credits/models/concerns/pay_subscription_extension.rb

@@ -35,21 +35,22 @@ module UsageCredits
 
       after_commit :update_fulfillment_on_renewal,        if: :subscription_renewed?
       after_commit :update_fulfillment_on_cancellation,   if: :subscription_canceled?
+      after_commit :handle_plan_change_wrapper
 
-      # TODO: handle plan changes (upgrades / downgrades)
       # TODO: handle paused subscriptions (may still have an "active" status?)
     end
 
     # Identify the usage_credits plan object
+    # NOTE: Not memoized because processor_plan can change, and we need the current value
     def credit_subscription_plan
-      @credit_subscription_plan ||= UsageCredits.configuration.find_subscription_plan_by_processor_id(processor_plan)
+      UsageCredits.configuration.find_subscription_plan_by_processor_id(processor_plan)
     end
 
     def provides_credits?
       credit_subscription_plan.present?
     end
 
-    def fullfillment_should_stop_at
+    def fulfillment_should_stop_at
       (ends_at || current_period_end)
     end
 
@@ -70,7 +71,34 @@ module UsageCredits
       # For now, we handle it by adding a validation to the Fulfillment model so that there's no two Fulfillment objects
       # with the same source_id -- so whichever of the two callbacks gets processed first wins, the other just fails.
       # That's how we prevent double credit awarding for now, but this race condition should be handled more elegantly.
-      UsageCredits::Fulfillment.exists?(source: self)
+      fulfillment = UsageCredits::Fulfillment.find_by(source: self)
+      return false unless fulfillment
+
+      # A stopped fulfillment (stops_at in the past) should NOT prevent reactivation
+      # This handles: credit → non-credit → credit transitions (after stop date)
+      return false if fulfillment.stops_at.present? && fulfillment.stops_at <= Time.current
+
+      # A fulfillment scheduled to stop (has stopped_reason but stops_at is in the future)
+      # should also allow reactivation - user changed their mind before the stop took effect
+      return false if fulfillment.metadata["stopped_reason"].present?
+
+      true
+    end
+
+    # Returns an existing fulfillment that is stopped or scheduled to stop
+    # Used for reactivation scenarios (credit → non-credit → credit)
+    def reactivatable_fulfillment
+      fulfillment = UsageCredits::Fulfillment.find_by(source: self)
+      return nil unless fulfillment
+
+      # Fulfillment is reactivatable if:
+      # 1. stops_at is in the past (actually stopped), OR
+      # 2. stopped_reason is set (scheduled to stop, but not yet)
+      is_stopped = fulfillment.stops_at.present? && fulfillment.stops_at <= Time.current
+      is_scheduled_to_stop = fulfillment.metadata["stopped_reason"].present?
+
+      return nil unless is_stopped || is_scheduled_to_stop
+      fulfillment
     end
 
     def subscription_renewed?
@@ -85,6 +113,26 @@ module UsageCredits
       saved_change_to_status? && status == "canceled"
     end
 
+    def plan_changed?
+      return false unless saved_change_to_processor_plan? && status == "active"
+
+      # The old plan ID must be present (not nil) - otherwise this is initial subscription creation
+      # not a plan change. Initial subscription is handled by handle_initial_award_and_fulfillment_setup.
+      old_plan_id = saved_change_to_processor_plan[0]
+      return false if old_plan_id.nil?
+
+      # Only trigger plan_change if the OLD plan was a credit plan.
+      # If old plan wasn't a credit plan (not in config), then handle_initial_award_and_fulfillment_setup
+      # will handle the "fresh start" case - we don't want to double-award credits.
+      old_plan = UsageCredits.configuration.find_subscription_plan_by_processor_id(old_plan_id)
+      return false unless old_plan.present?
+
+      # At this point, old plan provided credits. We handle:
+      # - Credit → Credit (upgrade/downgrade)
+      # - Credit → Non-credit (stop fulfillment)
+      true
+    end
+
     # =========================================
     # Actual fulfillment logic
     # =========================================
@@ -97,20 +145,24 @@ module UsageCredits
       # We only do immediate awarding if the subscription is trialing or active
       return unless ["trialing", "active"].include?(status)
 
-      # We'll skip if we already have a fulfillment record
+      # Check if we need to reactivate a stopped fulfillment (credit → non-credit → credit scenario)
+      existing_reactivatable_fulfillment = reactivatable_fulfillment
+      is_reactivation = existing_reactivatable_fulfillment.present?
+
+      # Skip if we already have an ACTIVE fulfillment record
       return if credits_already_fulfilled?
 
       plan = credit_subscription_plan
       wallet = customer.owner.credit_wallet
 
-      # Using the configured grace period
-      credits_expire_at = !plan.rollover_enabled ? (created_at + plan.parsed_fulfillment_period + UsageCredits.configuration.fulfillment_grace_period) : nil
+      # Calculate credit expiration using the shared helper
+      credits_expire_at = calculate_credit_expiration(plan, current_period_start)
 
-      Rails.logger.info "Fulfilling initial credits for subscription #{id}"
+      Rails.logger.info "Fulfilling #{is_reactivation ? 'reactivation' : 'initial'} credits for subscription #{id}"
       Rails.logger.info "  Status: #{status}"
       Rails.logger.info "  Plan: #{plan}"
 
-      # Transaction for atomic awarding + fulfillment creation
+      # Transaction for atomic awarding + fulfillment creation/reactivation
       ActiveRecord::Base.transaction do
 
         total_credits_awarded = 0
@@ -125,7 +177,7 @@ module UsageCredits
             expires_at: trial_ends_at,
             metadata: {
               subscription_id: id,
-              reason: "initial_trial_credits",
+              reason: is_reactivation ? "reactivation_trial_credits" : "initial_trial_credits",
               plan: processor_plan,
               fulfilled_at: Time.current
             }
@@ -135,8 +187,8 @@ module UsageCredits
 
         elsif status == "active"
 
-          # Awarding of signup bonus, if any
-          if plan.signup_bonus_credits.positive?
+          # Awarding of signup bonus, if any (only on initial setup, not reactivation)
+          if plan.signup_bonus_credits.positive? && !is_reactivation
             transaction = wallet.add_credits(plan.signup_bonus_credits,
               category: "subscription_signup_bonus",
               metadata: {
@@ -157,7 +209,7 @@ module UsageCredits
               expires_at: credits_expire_at,  # This will be nil if credit rollover is enabled
               metadata: {
                 subscription_id: id,
-                reason: "first_cycle",
+                reason: is_reactivation ? "reactivation" : "first_cycle",
                 plan: processor_plan,
                 fulfilled_at: Time.current
               }
@@ -167,37 +219,63 @@ module UsageCredits
           end
         end
 
-        # 2) Create a Fulfillment record for subsequent awarding
-        # Use current_period_start as the base time, falling back to created_at
+        # 2) Create or reactivate Fulfillment record for subsequent awarding
+        # Use current_period_start as the base time, falling back to Time.current
         period_start = if trial_ends_at && status == "trialing"
                       trial_ends_at
                     else
-                      current_period_start || created_at
+                      current_period_start || Time.current
                     end
 
         # Ensure next_fulfillment_at is in the future
         next_fulfillment_at = period_start + plan.parsed_fulfillment_period
         next_fulfillment_at = Time.current + plan.parsed_fulfillment_period if next_fulfillment_at <= Time.current
 
-        fulfillment = UsageCredits::Fulfillment.create!(
-          wallet: wallet,
-          source: self,
-          fulfillment_type: "subscription",
-          credits_last_fulfillment: total_credits_awarded,
-          fulfillment_period: plan.fulfillment_period_display,
-          last_fulfilled_at: Time.now,
-          next_fulfillment_at: next_fulfillment_at,
-          stops_at: fullfillment_should_stop_at, # Pre-emptively set when the fulfillment will stop, in case we miss a future event (like sub cancellation)
-          metadata: {
-            subscription_id: id,
-            plan: processor_plan,
-          }
-        )
+        if is_reactivation
+          # Reactivate the existing stopped/scheduled-to-stop fulfillment
+          # Merge metadata to preserve any custom keys while updating core fields
+          # Use string keys consistently to avoid duplicates after JSON serialization
+          existing_reactivatable_fulfillment.update!(
+            credits_last_fulfillment: total_credits_awarded,
+            fulfillment_period: plan.fulfillment_period_display,
+            last_fulfilled_at: Time.current,
+            next_fulfillment_at: next_fulfillment_at,
+            stops_at: fulfillment_should_stop_at,
+            metadata: existing_reactivatable_fulfillment.metadata
+              .except("stopped_reason", "stopped_at", "pending_plan_change", "plan_change_at")
+              .merge(
+                "subscription_id" => id,
+                "plan" => processor_plan,
+                "reactivated_at" => Time.current
+              )
+          )
+          fulfillment = existing_reactivatable_fulfillment
+
+          Rails.logger.info "Reactivated fulfillment #{fulfillment.id} for subscription #{id}"
+        else
+          # Create new fulfillment
+          # Use string keys consistently to avoid duplicates after JSON serialization
+          fulfillment = UsageCredits::Fulfillment.create!(
+            wallet: wallet,
+            source: self,
+            fulfillment_type: "subscription",
+            credits_last_fulfillment: total_credits_awarded,
+            fulfillment_period: plan.fulfillment_period_display,
+            last_fulfilled_at: Time.current,
+            next_fulfillment_at: next_fulfillment_at,
+            stops_at: fulfillment_should_stop_at, # Pre-emptively set when the fulfillment will stop, in case we miss a future event (like sub cancellation)
+            metadata: {
+              "subscription_id" => id,
+              "plan" => processor_plan,
+            }
+          )
+
+          Rails.logger.info "Initial fulfillment for subscription #{id} finished. Created fulfillment #{fulfillment.id}"
+        end
 
         # Link created transactions to the fulfillment object for traceability
         UsageCredits::Transaction.where(id: transaction_ids).update_all(fulfillment_id: fulfillment.id)
 
-        Rails.logger.info "Initial fulfillment for subscription #{id} finished. Created fulfillment #{fulfillment.id}"
       rescue => e
         Rails.logger.error "Failed to fulfill initial credits for subscription #{id}: #{e.message}"
         raise ActiveRecord::Rollback
@@ -214,8 +292,13 @@ module UsageCredits
       return unless fulfillment
 
       ActiveRecord::Base.transaction do
+        # Check if there's a pending plan change to apply
+        if fulfillment.metadata["pending_plan_change"].present?
+          apply_pending_plan_change(fulfillment)
+        end
+
         # Subscription renewed, we can set the new Fulfillment stops_at to the extended date
-        fulfillment.update!(stops_at: fullfillment_should_stop_at)
+        fulfillment.update!(stops_at: fulfillment_should_stop_at)
         Rails.logger.info "Fulfillment #{fulfillment.id} stops_at updated to #{fulfillment.stops_at}"
       rescue => e
         Rails.logger.error "Failed to extend fulfillment period for subscription #{id}: #{e.message}"
@@ -234,7 +317,7 @@ module UsageCredits
 
       ActiveRecord::Base.transaction do
         # Subscription cancelled, so stop awarding credits in the future
-        fulfillment.update!(stops_at: fullfillment_should_stop_at)
+        fulfillment.update!(stops_at: fulfillment_should_stop_at)
         Rails.logger.info "Fulfillment #{fulfillment.id} stops_at set to #{fulfillment.stops_at} due to cancellation"
       rescue => e
         Rails.logger.error "Failed to stop credit fulfillment for subscription #{id}: #{e.message}"
@@ -247,5 +330,265 @@ module UsageCredits
 
     end
 
+    # Wrapper to check condition and call handle_plan_change
+    def handle_plan_change_wrapper
+      return unless plan_changed?
+      handle_plan_change
+    end
+
+    # Handle plan changes (upgrades/downgrades)
+    def handle_plan_change
+      return unless has_valid_wallet?
+
+      fulfillment = UsageCredits::Fulfillment.find_by(source: self)
+      return unless fulfillment
+
+      # Debug logging to track plan changes and potential issues
+      Rails.logger.info "=" * 80
+      Rails.logger.info "[UsageCredits] Plan change detected for subscription #{id}"
+      Rails.logger.info "  Processor plan changed: #{saved_change_to_processor_plan.inspect}"
+      Rails.logger.info "  Subscription status: #{status}"
+      Rails.logger.info "  Current period end: #{current_period_end}"
+      Rails.logger.info "  Fulfillment metadata: #{fulfillment.metadata.inspect}"
+      Rails.logger.info "  Fulfillment period: #{fulfillment.fulfillment_period}"
+      Rails.logger.info "  Next fulfillment at: #{fulfillment.next_fulfillment_at}"
+
+      # Warn if current_period_end is nil for an active subscription - this is an edge case
+      # that could indicate incomplete data from the payment processor
+      if current_period_end.nil? && status == "active"
+        Rails.logger.warn "Subscription #{id} is active but current_period_end is nil - using Time.current as fallback for plan change scheduling"
+      end
+
+      # Get the current active plan (what the user is ACTUALLY on right now)
+      # This is crucial for handling multiple plan changes in one billing period
+      current_plan_id = fulfillment.metadata["plan"]
+      new_plan_id = processor_plan
+
+      Rails.logger.info "  Looking up current plan: #{current_plan_id}"
+      Rails.logger.info "  Looking up new plan: #{new_plan_id}"
+
+      current_plan = UsageCredits.configuration.find_subscription_plan_by_processor_id(current_plan_id)
+      new_plan = UsageCredits.configuration.find_subscription_plan_by_processor_id(new_plan_id)
+
+      Rails.logger.info "  Current plan found: #{current_plan&.name} (#{current_plan&.credits_per_period} credits)"
+      Rails.logger.info "  New plan found: #{new_plan&.name} (#{new_plan&.credits_per_period} credits)"
+
+      # Handle downgrade to a non-credit plan: schedule fulfillment stop for end of period
+      if new_plan.nil? && current_plan.present?
+        handle_downgrade_to_non_credit_plan(fulfillment)
+        return
+      end
+
+      return unless new_plan  # Neither current nor new plan provides credits - nothing to do
+
+      ActiveRecord::Base.transaction do
+        # FIRST: Check if returning to current plan (canceling a pending change)
+        # This must come first! Returning to current plan = no credits, just clear pending
+        # This matches Stripe's billing: no new charge means no new credits
+        if current_plan_id == new_plan_id
+          Rails.logger.info "  Action: Returning to current plan (clearing pending change)"
+          clear_pending_plan_change(fulfillment)
+          return
+        end
+
+        # Now compare credits to determine upgrade vs downgrade
+        current_credits = current_plan&.credits_per_period || 0
+        new_credits = new_plan.credits_per_period
+
+        Rails.logger.info "  Comparing credits: #{current_credits} → #{new_credits}"
+
+        if new_credits > current_credits
+          # UPGRADE: Grant new plan credits immediately
+          Rails.logger.info "  Action: UPGRADE detected - awarding #{new_credits} credits immediately"
+          handle_plan_upgrade(new_plan, fulfillment)
+        elsif new_credits < current_credits
+          # DOWNGRADE: Schedule for end of period (overwrites any previous pending)
+          Rails.logger.info "  Action: DOWNGRADE detected - scheduling for end of period"
+          handle_plan_downgrade(new_plan, fulfillment)
+        else
+          # Same credits amount, different plan - update metadata immediately
+          Rails.logger.info "  Action: Same credits, different plan - updating metadata only"
+          update_fulfillment_plan_metadata(fulfillment, new_plan_id)
+        end
+      rescue => e
+        Rails.logger.error "Failed to handle plan change for subscription #{id}: #{e.message}"
+        Rails.logger.error e.backtrace.join("\n")
+        raise ActiveRecord::Rollback
+      end
+
+      Rails.logger.info "  Plan change completed successfully"
+      Rails.logger.info "=" * 80
+    end
+
+    def handle_plan_upgrade(new_plan, fulfillment)
+      wallet = customer.owner.credit_wallet
+
+      Rails.logger.info "    [UPGRADE] Starting upgrade process"
+      Rails.logger.info "    [UPGRADE] Wallet ID: #{wallet.id}, Current balance: #{wallet.balance}"
+      Rails.logger.info "    [UPGRADE] Credits to award: #{new_plan.credits_per_period}"
+      Rails.logger.info "    [UPGRADE] New plan period: #{new_plan.fulfillment_period_display}"
+
+      # Calculate expiration using shared helper (uses current_period_end for upgrades)
+      credits_expire_at = calculate_credit_expiration(new_plan, current_period_end)
+
+      Rails.logger.info "    [UPGRADE] Credits expire at: #{credits_expire_at || 'never (rollover enabled)'}"
+
+      # Grant full new plan credits immediately
+      # Use string keys consistently to avoid duplicates after JSON serialization
+      wallet.add_credits(
+        new_plan.credits_per_period,
+        category: "subscription_upgrade",
+        expires_at: credits_expire_at,
+        metadata: {
+          "subscription_id" => id,
+          "plan" => processor_plan,
+          "reason" => "plan_upgrade",
+          "fulfilled_at" => Time.current
+        }
+      )
+
+      Rails.logger.info "    [UPGRADE] Credits awarded successfully"
+      Rails.logger.info "    [UPGRADE] New balance: #{wallet.reload.balance}"
+
+      # Calculate next fulfillment time based on the NEW plan's period
+      # This ensures the fulfillment schedule matches the new plan's cadence
+      next_fulfillment_at = Time.current + new_plan.parsed_fulfillment_period
+
+      Rails.logger.info "    [UPGRADE] Updating fulfillment record"
+      Rails.logger.info "    [UPGRADE] Old fulfillment_period: #{fulfillment.fulfillment_period}"
+      Rails.logger.info "    [UPGRADE] New fulfillment_period: #{new_plan.fulfillment_period_display}"
+      Rails.logger.info "    [UPGRADE] Old next_fulfillment_at: #{fulfillment.next_fulfillment_at}"
+      Rails.logger.info "    [UPGRADE] New next_fulfillment_at: #{next_fulfillment_at}"
+
+      # Update fulfillment with ALL new plan properties
+      # This includes the period display string and the next fulfillment time
+      # to ensure future fulfillments happen on the correct schedule
+      # Use string keys consistently to avoid duplicates after JSON serialization
+      fulfillment.update!(
+        fulfillment_period: new_plan.fulfillment_period_display,
+        next_fulfillment_at: next_fulfillment_at,
+        metadata: fulfillment.metadata
+          .except("pending_plan_change", "plan_change_at")
+          .merge("plan" => processor_plan)
+      )
+
+      Rails.logger.info "    [UPGRADE] Fulfillment updated successfully"
+      Rails.logger.info "Subscription #{id} upgraded to #{processor_plan}, granted #{new_plan.credits_per_period} credits"
+      Rails.logger.info "  Fulfillment period updated to: #{new_plan.fulfillment_period_display}"
+      Rails.logger.info "  Next fulfillment scheduled for: #{next_fulfillment_at}"
+    end
+
+    def handle_plan_downgrade(new_plan, fulfillment)
+      # Schedule the downgrade for end of current period
+      # User keeps current plan benefits until then
+      # Ensure schedule_time is never in the past (handles edge cases like stale data)
+      schedule_time = [current_period_end || Time.current, Time.current].max
+
+      # Use string keys consistently to avoid duplicates after JSON serialization
+      fulfillment.update!(
+        metadata: fulfillment.metadata.merge(
+          "pending_plan_change" => processor_plan,
+          "plan_change_at" => schedule_time
+        )
+      )
+
+      Rails.logger.info "Subscription #{id} downgrade to #{processor_plan} scheduled for #{schedule_time}"
+    end
+
+    def handle_downgrade_to_non_credit_plan(fulfillment)
+      # User is downgrading from a credit plan to a non-credit plan
+      # Schedule the fulfillment to stop at end of current period
+      # User keeps their existing credits (no clawback)
+      # Ensure schedule_time is never in the past
+      schedule_time = [current_period_end || Time.current, Time.current].max
+
+      ActiveRecord::Base.transaction do
+        # Use string keys consistently to avoid duplicates after JSON serialization
+        fulfillment.update!(
+          stops_at: schedule_time,
+          metadata: fulfillment.metadata.merge(
+            "stopped_reason" => "downgrade_to_non_credit_plan",
+            "stopped_at" => schedule_time
+          )
+        )
+
+        Rails.logger.info "Subscription #{id} downgraded to non-credit plan #{processor_plan}, fulfillment will stop at #{schedule_time}"
+      rescue => e
+        Rails.logger.error "Failed to handle downgrade to non-credit plan for subscription #{id}: #{e.message}"
+        Rails.logger.error e.backtrace.join("\n")
+        raise ActiveRecord::Rollback
+      end
+    end
+
+    def update_fulfillment_plan_metadata(fulfillment, new_plan_id)
+      # Use string keys consistently to avoid duplicates after JSON serialization
+      fulfillment.update!(
+        metadata: fulfillment.metadata.merge("plan" => new_plan_id)
+      )
+    end
+
+    # Clear any pending plan change metadata
+    # Used when user upgrades back to their current plan after scheduling a downgrade
+    def clear_pending_plan_change(fulfillment)
+      return unless fulfillment.metadata["pending_plan_change"].present?
+
+      fulfillment.update!(
+        metadata: fulfillment.metadata.except("pending_plan_change", "plan_change_at")
+      )
+
+      Rails.logger.info "Subscription #{id} pending plan change cleared (returned to current plan)"
+    end
+
+    def apply_pending_plan_change(fulfillment)
+      pending_plan = fulfillment.metadata["pending_plan_change"]
+
+      # Validate that the pending plan still exists in configuration
+      # This handles the edge case where an admin removes a plan after a user scheduled a downgrade
+      unless UsageCredits.configuration.find_subscription_plan_by_processor_id(pending_plan)
+        Rails.logger.error "Cannot apply pending plan change for subscription #{id}: plan '#{pending_plan}' not found in configuration"
+        # Clear the invalid pending change to prevent repeated failures
+        fulfillment.update!(
+          metadata: fulfillment.metadata.except("pending_plan_change", "plan_change_at")
+        )
+        return
+      end
+
+      # Update to the new plan and clear the pending change
+      # Use string keys consistently to avoid duplicates after JSON serialization
+      fulfillment.update!(
+        metadata: fulfillment.metadata
+          .except("pending_plan_change", "plan_change_at")
+          .merge("plan" => pending_plan)
+      )
+
+      Rails.logger.info "Applied pending plan change for subscription #{id}: now on #{pending_plan}"
+    end
+
+    # =========================================
+    # Helper Methods
+    # =========================================
+
+    # Calculate credit expiration date for a given plan
+    # Handles the edge case where base_time might be in the past (e.g., paused subscription reactivated)
+    # by ensuring we never create credits that are already expired
+    def calculate_credit_expiration(plan, base_time = nil)
+      return nil if plan.rollover_enabled
+
+      # Use the provided base_time or fall back to current time
+      # Crucially: ensure we never use a time in the past, which would create already-expired credits
+      # This fixes the bug where a paused subscription reactivated would have past expiration dates
+      effective_base = [base_time || Time.current, Time.current].max
+
+      # Cap the grace period to the fulfillment period to prevent balance accumulation
+      # when fulfillment_period << grace_period (e.g., 15 seconds vs 5 minutes)
+      fulfillment_period = plan.parsed_fulfillment_period
+      effective_grace = [
+        UsageCredits.configuration.fulfillment_grace_period,
+        fulfillment_period
+      ].min
+
+      effective_base + fulfillment_period + effective_grace
+    end
+
   end
 end

data/lib/usage_credits/models/credit_subscription_plan.rb

@@ -19,7 +19,7 @@ module UsageCredits
 
     attr_writer :fulfillment_period
 
-    MIN_PERIOD = 1.day
+    MIN_PERIOD = 1.day  # Deprecated: Use UsageCredits.configuration.min_fulfillment_period instead
 
     def initialize(name)
       @name = name
@@ -88,32 +88,134 @@ module UsageCredits
     # Payment Processor Integration
     # =========================================
 
-    # Set the processor-specific plan ID
+    # Set the processor-specific plan ID(s)
+    # Accepts either a single ID (String) or multiple period-specific IDs (Hash)
+    #
+    # @param processor [Symbol] The payment processor (e.g., :stripe)
+    # @param id [String, Hash] Single ID or hash of period => ID pairs
+    # @example Single ID (backward compatible)
+    #   processor_plan(:stripe, "price_123")
+    # @example Multiple periods
+    #   processor_plan(:stripe, { month: "price_m", year: "price_y" })
     def processor_plan(processor, id)
+      if id.is_a?(Hash)
+        raise ArgumentError, "Period hash cannot be empty" if id.empty?
+        # Normalize all keys to symbols for consistent lookup
+        id = id.transform_keys(&:to_sym)
+      end
       processor_plan_ids[processor.to_sym] = id
     end
 
-    # Get the plan ID for a specific processor
-    def plan_id_for(processor)
-      processor_plan_ids[processor.to_sym]
+    # Get the plan ID(s) for a specific processor
+    # @param processor [Symbol] The payment processor
+    # @param period [Symbol, nil] Optional specific period to retrieve
+    # @return [String, Hash, nil] Single ID, hash of IDs, or nil
+    def plan_id_for(processor, period: nil)
+      ids = processor_plan_ids[processor.to_sym]
+
+      # If no period specified, return as-is (String or Hash)
+      return ids if period.nil?
+
+      # If ids is a Hash, return the specific period
+      return ids[period.to_sym] if ids.is_a?(Hash)
+
+      # If ids is a String and they asked for a period, return nil (not multi-period)
+      nil
     end
 
-    # Shorthand for Stripe price ID
-    def stripe_price(id = nil)
-      if id.nil?
-        plan_id_for(:stripe) # getter
+    # Shorthand for Stripe price ID(s)
+    # Supports both single price and multi-period prices
+    #
+    # @overload stripe_price
+    #   Get all Stripe price IDs
+    #   @return [String, Hash] Single price ID or hash of period => price_id
+    # @overload stripe_price(id)
+    #   Set a single Stripe price ID (backward compatible)
+    #   @param id [String] The Stripe price ID
+    # @overload stripe_price(prices)
+    #   Set multiple period-specific Stripe price IDs
+    #   @param prices [Hash] Hash of period => price_id (e.g., { month: "price_m", year: "price_y" })
+    # @overload stripe_price(period)
+    #   Get Stripe price ID for a specific period
+    #   @param period [Symbol] The billing period (e.g., :month, :year)
+    #   @return [String, nil] Price ID for that period
+    #
+    # @example Get all prices
+    #   plan.stripe_price # => { month: "price_m", year: "price_y" }
+    # @example Get specific period
+    #   plan.stripe_price(:month) # => "price_m"
+    # @example Set single price (backward compatible)
+    #   stripe_price "price_123"
+    # @example Set multiple periods
+    #   stripe_price month: "price_m", year: "price_y"
+    def stripe_price(id_or_period = nil)
+      if id_or_period.nil?
+        # Getter: return all prices
+        plan_id_for(:stripe)
+      elsif id_or_period.is_a?(Hash)
+        # Setter: hash of period => price_id
+        processor_plan(:stripe, id_or_period)
+      elsif id_or_period.is_a?(Symbol)
+        # Getter: specific period
+        plan_id_for(:stripe, period: id_or_period)
       else
-        processor_plan(:stripe, id) # setter
+        # Setter: single price ID (backward compatible)
+        processor_plan(:stripe, id_or_period)
+      end
+    end
+
+    # Get all Stripe price IDs as a hash (always returns hash format)
+    # @return [Hash] Hash of period => price_id, or { default: price_id } for single-price plans
+    def stripe_prices
+      ids = plan_id_for(:stripe)
+      return {} if ids.nil?
+      return ids if ids.is_a?(Hash)
+      { default: ids } # Wrap single ID in hash for consistency
+    end
+
+    # Check if this plan matches a given processor price ID
+    # Works with both single-price and multi-period plans
+    # @param processor_id [String] The price ID to match
+    # @return [Boolean] True if this plan includes the given price ID
+    def matches_processor_id?(processor_id)
+      processor_plan_ids.values.any? do |ids|
+        if ids.is_a?(Hash)
+          ids.values.include?(processor_id)
+        else
+          ids == processor_id
+        end
       end
     end
 
     # Create a checkout session for this subscription plan
-    def create_checkout_session(user, success_url:, cancel_url:, processor: :stripe)
+    # @param user [Object] The user creating the checkout session
+    # @param success_url [String] URL to redirect after successful checkout
+    # @param cancel_url [String] URL to redirect if checkout is cancelled
+    # @param processor [Symbol] Payment processor to use (default: :stripe)
+    # @param period [Symbol, nil] Billing period for multi-period plans (e.g., :month, :year)
+    #
+    # @example Single-price plan (backward compatible)
+    #   plan.create_checkout_session(user, success_url: "/success", cancel_url: "/cancel")
+    #
+    # @example Multi-period plan (must specify period)
+    #   plan.create_checkout_session(user, success_url: "/success", cancel_url: "/cancel", period: :month)
+    #   plan.create_checkout_session(user, success_url: "/success", cancel_url: "/cancel", period: :year)
+    def create_checkout_session(user, success_url:, cancel_url:, processor: :stripe, period: nil)
       raise ArgumentError, "User must respond to payment_processor" unless user.respond_to?(:payment_processor)
       raise ArgumentError, "No fulfillment period configured for plan: #{name}" unless fulfillment_period
 
-      plan_id = plan_id_for(processor)
-      raise ArgumentError, "No #{processor.to_s.titleize} plan ID configured for plan: #{name}" unless plan_id
+      plan_ids = plan_id_for(processor)
+      raise ArgumentError, "No #{processor.to_s.titleize} plan ID configured for plan: #{name}" unless plan_ids
+
+      # Determine which price ID to use
+      plan_id = if plan_ids.is_a?(Hash)
+        # Multi-period plan: period is required
+        raise ArgumentError, "This plan has multiple billing periods (#{plan_ids.keys.join(', ')}). Please specify period: parameter (e.g., period: :month)" if period.nil?
+        plan_ids[period.to_sym] || raise(ArgumentError, "Period #{period.inspect} not found. Available periods: #{plan_ids.keys.inspect}")
+      else
+        # Single-price plan: use the ID directly
+        plan_ids
+      end
 
       case processor
       when :stripe
@@ -157,7 +259,6 @@ module UsageCredits
         }],
         success_url: success_url,
         cancel_url: cancel_url,
-        payment_intent_data: { metadata: base_metadata },
         subscription_data: { metadata: base_metadata }
       )
     end