pricing_plans 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a22c4cf12c06ba9c2e7d649811c286044ae8ff5f9586bea223584fa10b054e4
-  data.tar.gz: 55ee30afed8af0fd32018ca6d706ab0efe4cd745346fc24787d90ddbcf815071
+  metadata.gz: 8003fe05eaafc824f16d2c6dd72f067c04fd9417f066a1a9e9197f42d30518e0
+  data.tar.gz: 512a6cc888ce5261ecd37fb7b59e9bd5c16c3571d754154b0ee0e30c385e9c36
 SHA512:
-  metadata.gz: bf40f8507ad67ca84c0e46e390db6fdb65e13ea247f5f1a12446c88ec6eaff59d0b519f2951538a59858f2b4222c4257112c5f13d4697a78fc84124e6c713782
-  data.tar.gz: 2a3906414a684300257e1b20b1f4b3cbd278ef7631c7a4f7c675f006483cb107145c323e61072e0fe2fe91976ca140b86dc617d3a14cc1495a010cf8c897c19a
+  metadata.gz: 617a80ea706ea417eb1f8ad8a8676c9690d852a66b454793ba47efe2bb4d112873b13f8a7e7fec7e6e9c9ed7833ae3d36f834be519f9b90bbc4ef18cac6de6d9
+  data.tar.gz: 6e86e014b7a3652a48725677819c324fedf23f924db740f30a2f2cf05a3f138673edf8b9d2d95a8c9fcd915e75438613b335fefad3867c1be0fb10389df71353

data/.rubocop.yml

@@ -134,4 +134,4 @@ Style/GlobalVars:
 
 # Database-related
 Style/NumericLiterals:
-  Enabled: false  # Allow raw numbers in database IDs/amounts
+  Enabled: false  # Allow raw numbers in database IDs/amounts

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [0.5.0] - 2026-08-31
+
+- Add intention-revealing pricing plan override APIs: `override_pricing_plan!`, `clear_pricing_plan_override!`, `pricing_plan_overridden?`, `pricing_plan_override`, and `pricing_plan_override_source`
+- Require explicit `source:` provenance when creating overrides through the new API
+- Remove the implicit `"manual"` source default from newly generated assignment tables; legacy APIs still supply it explicitly for compatibility
+- Add matching explicit `PlanResolver` and `Assignment` entry points, plus symmetric `override_pricing_plan_for!` and `clear_pricing_plan_override_for!` helpers on `Limitable` models, for lower-level use cases
+- Add override-oriented provenance readers to `PlanResolution` while preserving its assignment-oriented compatibility readers
+- Deprecate the ambiguous `assign_pricing_plan!`, `remove_pricing_plan!`, `assign_plan_manually!`, `remove_manual_assignment!`, `assign_plan_to`, and `remove_assignment_for` APIs through a gem-specific Active Support deprecator
+- Guard legacy assignments of the configured default plan with configurable `:allow`, `:warn`, or `:raise` behavior; upgraded applications default to `:warn`, while newly generated initializers choose the safer `:raise`
+- Clarify that ordinary free/default accounts should remain unassigned and that intentional default-tier pinning remains supported through the explicit override API
+
 ## [0.4.1] - 2026-08-24
 
 - **Never 500 a pricing page when Stripe is unreachable**: `Plan#currency_symbol` was the one Stripe lookup without a rescue — a Stripe outage, rate limit, or missing API key (any test/CI environment) raised straight through the pricing page. It now degrades to `default_currency_symbol` like every other presentation method (#24)

data/README.md

@@ -162,10 +162,23 @@ Integrating payment processing (Stripe, `pay`, etc.) is relatively straightforwa
 
 The `pricing_plans` gem needs three new models in the schema in order to work: `Assignment`, `EnforcementState`, and `Usage`. Why are they needed?
 
-- `PricingPlans::Assignment` allow manual plan overrides independent of billing system (or before you wire up Stripe/Pay). Great for admin toggles, trials, demos.
-  - What: The arbitrary `plan_key` and a `source` label (default "manual"). Unique per plan_owner.
-  - How it's used: `PlanResolver` checks manual assignment → Pay → default plan. Manual assignments (admin overrides) take precedence over subscription-based plans. You can call `assign_pricing_plan!` and `remove_pricing_plan!` on the plan_owner.
-  - Provenance helpers: `current_pricing_plan_source` tells you whether the effective plan came from `:assignment`, `:subscription`, or `:default`, and `current_pricing_plan_resolution` exposes the assignment and current subscription objects when you need both entitlement and billing context.
+- `PricingPlans::Assignment` stores explicit pricing plan overrides independently of the billing system. This is useful for gifts, employee access, demos, support interventions, and grandfathered customers.
+  - What: A `plan_key` and a required provenance label such as `"admin"`, `"customer_success_gift"`, or `"legacy_import"`. There can be only one override per plan owner.
+  - How it's used: `PlanResolver` checks explicit override → Pay subscription → configured default. Every persisted override takes precedence over subscription-based plans, including an override whose key happens to equal the configured default.
+  - Intention-revealing API: call `plan_owner.override_pricing_plan!(:pro, source: "admin")` to create or update an override, and `plan_owner.clear_pricing_plan_override!` to resume normal subscription/default resolution.
+  - Provenance helpers: `pricing_plan_overridden?`, `pricing_plan_override`, and `pricing_plan_override_source` expose the override directly. `current_pricing_plan_resolution` preserves both entitlement and billing context when an override and a subscription coexist.
+
+An ordinary free/default account needs no assignment row:
+
+```ruby
+# Intentional exception: pin this organization to Pro independently of billing.
+organization.override_pricing_plan!(:pro, source: "customer_success_gift")
+
+# Resume automatic Pay subscription / configured default resolution.
+organization.clear_pricing_plan_override!
+```
+
+The old `assign_pricing_plan!` and `remove_pricing_plan!` names are deprecated because they hide the override semantics. See [Check and explicitly override plans](docs/03-model-helpers.md#check-and-explicitly-override-plans) for migration and strict-mode guidance.
 
 - `PricingPlans::EnforcementState` tracks per-plan_owner per-limit enforcement state for persistent caps and per-period allowances (grace/warnings/block state) in a race-safe way.
   - What: `exceeded_at`, `blocked_at`, last warning info, and a small JSON `data` column where we persist plan-derived parameters like grace period seconds.
@@ -196,7 +209,7 @@ Enforcing pricing plans is one of those boring plumbing problems that look easy
 
 ## Downgrades and overages
 
-When a customer moves to a lower plan (via Stripe/Pay or manual assignment), the new plan’s limits start applying immediately. Existing resources are never auto‑deleted by the gem; instead:
+When a customer moves to a lower plan (via Stripe/Pay or an explicit override), the new plan’s limits start applying immediately. Existing resources are never auto‑deleted by the gem; instead:
 
 - **Persistent caps** (e.g., `:projects, to: 3`): We count live rows. If the account is now over the new cap, creations will be blocked (or put into grace/warn depending on `after_limit`). Users must remediate by deleting/archiving until under cap.
 - 

data/docs/01-define-pricing-plans.md

@@ -188,7 +188,7 @@ Callback timing:
 
 ```ruby
 # pro allows 3 custom models per month
-PricingPlans::Assignment.assign_plan_to(org, :pro)
+org.override_pricing_plan!(:pro, source: "test_setup")
 
 travel_to(Time.parse("2025-01-15 12:00:00 UTC")) do
   3.times { org.custom_models.create!(name: "Model") }
@@ -457,7 +457,7 @@ end
 **Important notes:**
 - Hidden plans can be the `default!` plan (common pattern for "unsubscribed" users)
 - Hidden plans **cannot** be the `highlighted!` plan (validation error - highlighted plans must be visible)
-- Users can still be on hidden plans (via Pay subscription, manual assignment, or default)
+- Users can still be on hidden plans (via Pay subscription, an explicit pricing plan override, or the configured default)
 - Internal APIs (`Registry.plans`, `PlanResolver`) can still access hidden plans
 - Pay gem can still resolve subscriptions to hidden plans (useful for grandfathered customers)
 

data/docs/03-model-helpers.md

@@ -290,18 +290,64 @@ You can also use the top-level equivalents if you prefer: `PricingPlans.severity
 
 ## Other helpers and methods
 
-### Check and override plans
+### Check and explicitly override plans
+
+An override is an intentional exception to normal plan resolution. It is useful for gifts, employee accounts, support interventions, demos, and grandfathering. The method names deliberately say **override** because an override always takes precedence over both Pay subscriptions and the configured default:
+
+```ruby
+user.current_pricing_plan                             # => PricingPlans::Plan
+user.current_pricing_plan_source                      # => :assignment, :subscription, :default
+user.current_pricing_plan_resolution                  # => PricingPlans::PlanResolution
+
+user.override_pricing_plan!(:pro, source: "admin")   # create/update an explicit override
+user.pricing_plan_overridden?                         # => true
+user.pricing_plan_override                            # => PricingPlans::Assignment
+user.pricing_plan_override_source                     # => "admin"
+user.clear_pricing_plan_override!                     # resume subscription/default resolution
+```
+
+> [!WARNING]
+> Explicitly overriding to the configured default plan is still an override. For
+> example, `user.override_pricing_plan!(:free, source: "admin_downgrade")`
+> creates an assignment row and continues to take precedence over future Pay
+> subscriptions. That behavior supports intentional default-tier pinning. For an
+> ordinary free/default account, create no assignment. If an override already
+> exists, call `user.clear_pricing_plan_override!` to resume normal resolution.
+
+The `source:` keyword is required by the explicit API. Use a stable, auditable description of why the exception exists—such as `"admin"`, `"customer_success_gift"`, `"employee_access"`, or `"legacy_import"`. The source is provenance; it does not alter precedence. Every override wins regardless of its source label.
+
+Newly generated assignment tables do not have a database default for `source`, so direct model writes must also state their provenance. Applications installed with an older gem version may still have the historical `"manual"` database default; the explicit public API does not rely on it.
+
+#### Migrating from the old assignment API
+
+`assign_pricing_plan!` and `remove_pricing_plan!` are deprecated because their names do not reveal that they create and clear persistent overrides. Replace them directly:
 
-You can also check and override the current pricing plan for any user, which comes handy as an admin:
 ```ruby
-user.current_pricing_plan                    # => PricingPlans::Plan
-user.current_pricing_plan_source             # => :assignment, :subscription, :default
-user.current_pricing_plan_resolution         # => PricingPlans::PlanResolution
-user.assign_pricing_plan!(:pro)              # manual assignment override
-user.remove_pricing_plan!                    # remove manual override (fallback to default)
+# Before: ambiguous and source defaulted silently to "manual"
+user.assign_pricing_plan!(:pro)
+user.remove_pricing_plan!
+
+# After: intent and provenance are explicit
+user.override_pricing_plan!(:pro, source: "admin")
+user.clear_pricing_plan_override!
 ```
 
-**Performance note:** Each call to `current_pricing_plan`, `current_pricing_plan_source`, or `current_pricing_plan_resolution` performs a fresh database lookup. If you need both the plan and its provenance, call `current_pricing_plan_resolution` once and read both values from that object — this avoids duplicate queries.
+Legacy calls continue to work during the deprecation window and emit a gem-specific Active Support deprecation warning. Assigning the configured default through a legacy API receives an additional guard because it is usually accidental. Its behavior is configurable:
+
+```ruby
+PricingPlans.configure do |config|
+  # :warn  — default for upgraded applications; preserve behavior and warn
+  # :raise — recommended; reject legacy default-plan assignments before writing
+  # :allow — migration escape hatch; emit only the general deprecation warning
+  config.legacy_default_plan_assignment_behavior = :raise
+end
+```
+
+The strict `:raise` behavior raises `PricingPlans::LegacyDefaultPlanAssignmentError` and writes no assignment. It never blocks the explicit `override_pricing_plan!` API, even when the target is the default plan, because that method already states the caller's intent. Newly generated initializers use `:raise`.
+
+The low-level legacy methods—`PricingPlans::PlanResolver.assign_plan_manually!`, `PricingPlans::PlanResolver.remove_manual_assignment!`, `PricingPlans::Assignment.assign_plan_to`, and `PricingPlans::Assignment.remove_assignment_for`—are deprecated under the same policy. Prefer `PlanResolver.override_pricing_plan_for!`, `PlanResolver.clear_pricing_plan_override_for!`, `Assignment.create_or_update_pricing_plan_override_for!`, and `Assignment.clear_pricing_plan_override_for!` when a lower-level API is genuinely necessary. Models that include `PricingPlans::Limitable` also expose the symmetric class-level pair `override_pricing_plan_for!` and `clear_pricing_plan_override_for!` for compatibility with their previous owner-aware assignment helper.
+
+**Performance note:** Each plan/provenance helper performs a fresh database lookup. If you need both the effective plan and its provenance, call `current_pricing_plan_resolution` once and read both from that object.
 
 If you need the full provenance, use the resolution object:
 
@@ -309,13 +355,18 @@ If you need the full provenance, use the resolution object:
 resolution = user.current_pricing_plan_resolution
 
 resolution.plan.key                          # => :enterprise
-resolution.source                            # => :assignment
-resolution.assignment                        # => PricingPlans::Assignment | nil
-resolution.assignment_source                 # => "admin" | "manual" | nil
+resolution.source                            # => :assignment (compatibility value)
+resolution.pricing_plan_overridden?           # => true
+resolution.pricing_plan_override              # => PricingPlans::Assignment | nil
+resolution.pricing_plan_override_source       # => "admin" | "legacy_import" | nil
 resolution.subscription                      # => Pay subscription | nil
+
+# Storage-oriented compatibility readers remain available:
+resolution.assignment                        # => same object as pricing_plan_override
+resolution.assignment_source                 # => same value as pricing_plan_override_source
 ```
 
-This distinction matters: the **effective pricing plan** is what controls entitlements and limits inside your app. The **Pay/Stripe subscription state** is billing-facing. A manual assignment may intentionally override the subscription-backed plan while still leaving the underlying subscription present for billing operations.
+This distinction matters: the **effective pricing plan** controls entitlements and limits inside your app, while the **Pay/Stripe subscription state** is billing-facing. An explicit override may intentionally control entitlements while the underlying subscription remains available for billing operations. Clearing the override does not cancel or modify billing; it simply lets subscription/default resolution take control again.
 
 **Edge case:** `source` can be `:default` even when `subscription` is non-nil. This happens when a Pay subscription exists but its `processor_plan` (Stripe price ID) doesn't map to any plan in your registry. The subscription is preserved for billing context, but the effective plan falls back to your configured default.
 

data/docs/06-gem-compatibility.md

@@ -14,7 +14,19 @@ There's nothing to do on your end to make `pricing_plans` work with `pay`!
 
 As long as your `pricing_plans` config (`config/initializers/pricing_plans.rb`) contains a plan with the correct `stripe_price` ID, whenever a subscription to that Stripe price ID is found through the `pay` gem, `pricing_plans` will understand the user is subscribed to that plan automatically, and will start enforcing the corresponding limits.
 
-The way `pricing_plans` works doesn't require any data migration, or callback setup, or any manual action. You don't need to call `assign_pricing_plan!` at all at any point, unless you're trying to something like overriding a plan, gifting users access to plans without any payment, or things like that.
+The way `pricing_plans` works doesn't require any data migration, callback setup, or assignment during signup. Do not call an override API for ordinary plan selection or after a successful Pay checkout: Pay subscriptions are discovered automatically.
+
+Use `plan_owner.override_pricing_plan!(:pro, source: "customer_success_gift")` only when you deliberately want an exception that wins over billing. In particular, do not override to the default/free plan during ordinary signup or free-plan selection. Leave the owner without an override—or call `plan_owner.clear_pricing_plan_override!`—to use Pay/default resolution normally.
+
+The deprecated `assign_pricing_plan!` API now warns, and upgraded applications can turn accidental legacy default-plan assignments into errors:
+
+```ruby
+PricingPlans.configure do |config|
+  config.legacy_default_plan_assignment_behavior = :raise
+end
+```
+
+Newly generated initializers enable this strict behavior. Intentional default-tier pinning remains available through the self-documenting explicit API: `plan_owner.override_pricing_plan!(:free, source: "admin_downgrade")`.
 
 As long as a matching `stripe_price` is found in the `pricing_plans.rb` initializer, the gem will know a user subscribed to that Stripe price ID is under the corresponding plan. Essentially, the gem just looks at the current `pay` subscriptions of your user. If a matching price ID is found in the `pricing_plans` configuration file, it enforces the corresponding limits.
 

data/lib/generators/pricing_plans/install/templates/create_pricing_plans_tables.rb.erb

@@ -57,7 +57,7 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
     create_table :pricing_plans_assignments, id: primary_key_type do |t|
       t.references :plan_owner, polymorphic: true, null: false, type: foreign_key_type
       t.string :plan_key, null: false
-      t.string :source, null: false, default: "manual"
+      t.string :source, null: false
 
       t.timestamps
     end
@@ -88,4 +88,3 @@ class CreatePricingPlansTables < ActiveRecord::Migration<%= migration_version %>
   end
 end
 
-

data/lib/generators/pricing_plans/install/templates/initializer.rb

@@ -36,6 +36,11 @@ PricingPlans.configure do |config|
     allows    :api_access, :premium_features
   end
 
+  # Reject the deprecated, ambiguous assignment API if it is used to assign
+  # the configured default plan. Use `override_pricing_plan!(..., source: ...)`
+  # for deliberate exceptions and no assignment at all for ordinary defaults.
+  config.legacy_default_plan_assignment_behavior = :raise
+
 
   # Optional settings
 

data/lib/pricing_plans/configuration.rb

@@ -6,7 +6,18 @@ module PricingPlans
   class Configuration
     include DSL
 
+    LEGACY_DEFAULT_PLAN_ASSIGNMENT_BEHAVIORS = [:allow, :warn, :raise].freeze
+
+    def self.legacy_default_plan_assignment_behaviors_description
+      descriptions = LEGACY_DEFAULT_PLAN_ASSIGNMENT_BEHAVIORS.map(&:inspect)
+      "#{descriptions[0..-2].join(', ')}, or #{descriptions.last}"
+    end
+
     attr_accessor :default_plan, :highlighted_plan, :period_cycle
+    # Controls what the deprecated assignment APIs do when they are asked to
+    # assign the configured default plan. Explicit override APIs are never
+    # affected because their names already communicate the caller's intent.
+    attr_accessor :legacy_default_plan_assignment_behavior
     # Optional ergonomics
     attr_accessor :default_cta_text, :default_cta_url
     # Debug mode - set to true to enable debug output
@@ -57,6 +68,7 @@ module PricingPlans
       @default_plan = nil
       @highlighted_plan = nil
       @period_cycle = :billing_cycle
+      @legacy_default_plan_assignment_behavior = :warn
       @default_cta_text = nil
       @default_cta_url = nil
       @message_builder = nil
@@ -151,6 +163,7 @@ module PricingPlans
       validate_required_settings!
       validate_plan_references!
       validate_dsl_markers!
+      validate_legacy_default_plan_assignment_behavior!
       validate_plans!
     end
     def select_defaults_from_dsl!
@@ -205,5 +218,13 @@ module PricingPlans
     def validate_plans!
       @plans.each_value(&:validate!)
     end
+
+    def validate_legacy_default_plan_assignment_behavior!
+      return if LEGACY_DEFAULT_PLAN_ASSIGNMENT_BEHAVIORS.include?(@legacy_default_plan_assignment_behavior)
+
+      raise PricingPlans::ConfigurationError,
+        "legacy_default_plan_assignment_behavior must be " \
+        "#{self.class.legacy_default_plan_assignment_behaviors_description}"
+    end
   end
 end

data/lib/pricing_plans/engine.rb

@@ -4,6 +4,10 @@ module PricingPlans
   class Engine < ::Rails::Engine
     isolate_namespace PricingPlans
 
+    initializer "pricing_plans.deprecator" do |app|
+      app.deprecators[:pricing_plans] = PricingPlans.deprecator if app.respond_to?(:deprecators)
+    end
+
     initializer "pricing_plans.active_record" do
       ActiveSupport.on_load(:active_record) do
         # Make models available

data/lib/pricing_plans/legacy_plan_assignment_api.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Compatibility boundary for assignment-era APIs whose names do not make it
+  # clear that every persisted assignment is a pricing plan override.
+  #
+  # Keep all warnings and the default-plan safety policy here so every legacy
+  # entry point behaves identically. New code should bypass this class and use
+  # the explicit override APIs.
+  class LegacyPlanAssignmentApi
+    class << self
+      def create_or_update_override!(plan_owner, plan_key, source:, called_method_name:)
+        handle_deprecated_assignment_call!(plan_key, called_method_name)
+
+        Assignment.create_or_update_pricing_plan_override_for!(
+          plan_owner,
+          plan_key,
+          source: source
+        )
+      end
+
+      def clear_override!(plan_owner, called_method_name:)
+        PricingPlans.deprecator.warn(
+          "`#{called_method_name}` is deprecated because its name does not make clear " \
+          "that it only clears a persistent pricing plan override. " \
+          "Use `clear_pricing_plan_override!` instead."
+        )
+
+        Assignment.clear_pricing_plan_override_for!(plan_owner)
+      end
+
+      private
+
+      def handle_deprecated_assignment_call!(plan_key, called_method_name)
+        if configured_default_plan_key?(plan_key)
+          handle_deprecated_default_plan_assignment!(plan_key, called_method_name)
+        else
+          warn_about_deprecated_assignment_api(called_method_name)
+        end
+      end
+
+      def configured_default_plan_key?(plan_key)
+        default_plan_key = Registry.default_plan&.key
+        default_plan_key && plan_key.to_s == default_plan_key.to_s
+      end
+
+      def handle_deprecated_default_plan_assignment!(plan_key, called_method_name)
+        case PricingPlans.configuration.legacy_default_plan_assignment_behavior
+        when :allow
+          warn_about_deprecated_assignment_api(called_method_name)
+        when :warn
+          PricingPlans.deprecator.warn(default_plan_assignment_message(plan_key, called_method_name))
+        when :raise
+          raise LegacyDefaultPlanAssignmentError.new(
+            default_plan_assignment_message(plan_key, called_method_name),
+            configured_default_plan_key: plan_key,
+            legacy_assignment_method_name: called_method_name
+          )
+        else
+          raise ConfigurationError,
+            "legacy_default_plan_assignment_behavior must be " \
+            "#{Configuration.legacy_default_plan_assignment_behaviors_description}"
+        end
+      end
+
+      def warn_about_deprecated_assignment_api(called_method_name)
+        PricingPlans.deprecator.warn(
+          "`#{called_method_name}` is deprecated because assigning a plan creates a " \
+          "persistent pricing plan override. Use `override_pricing_plan!(plan_key, " \
+          "source: ...)` instead."
+        )
+      end
+
+      def default_plan_assignment_message(plan_key, called_method_name)
+        "`#{called_method_name}` was asked to assign the configured default plan " \
+          ":#{plan_key}. That creates a persistent pricing plan override; it does not " \
+          "select the normal default-plan resolution and it will take precedence over " \
+          "future subscriptions. Use `override_pricing_plan!(:#{plan_key}, source: ...)` " \
+          "when the override is intentional, or `clear_pricing_plan_override!` to use " \
+          "normal subscription/default resolution."
+      end
+    end
+  end
+end

data/lib/pricing_plans/limitable.rb

@@ -33,8 +33,21 @@ module PricingPlans
         PlanResolver.effective_plan_for(self)
       end
 
+      define_singleton_method :override_pricing_plan_for! do |plan_owner, plan_key, source:|
+        PlanResolver.override_pricing_plan_for!(plan_owner, plan_key, source: source)
+      end
+
+      define_singleton_method :clear_pricing_plan_override_for! do |plan_owner|
+        PlanResolver.clear_pricing_plan_override_for!(plan_owner)
+      end
+
       define_singleton_method :assign_pricing_plan! do |plan_owner, plan_key, source: "manual"|
-        Assignment.assign_plan_to(plan_owner, plan_key, source: source)
+        LegacyPlanAssignmentApi.create_or_update_override!(
+          plan_owner,
+          plan_key,
+          source: source,
+          called_method_name: "#{name}.assign_pricing_plan!"
+        )
       end
     end
 

data/lib/pricing_plans/models/assignment.rb

@@ -20,7 +20,7 @@ module PricingPlans
       Registry.plan(plan_key.to_sym)
     end
 
-    def self.assign_plan_to(plan_owner, plan_key, source: "manual")
+    def self.create_or_update_pricing_plan_override_for!(plan_owner, plan_key, source:)
       assignment = find_or_initialize_by(
         plan_owner_type: plan_owner.class.name,
         plan_owner_id: plan_owner.id
@@ -35,13 +35,29 @@ module PricingPlans
       assignment
     end
 
-    def self.remove_assignment_for(plan_owner)
+    def self.clear_pricing_plan_override_for!(plan_owner)
       where(
         plan_owner_type: plan_owner.class.name,
         plan_owner_id: plan_owner.id
       ).destroy_all
     end
 
+    def self.assign_plan_to(plan_owner, plan_key, source: "manual")
+      LegacyPlanAssignmentApi.create_or_update_override!(
+        plan_owner,
+        plan_key,
+        source: source,
+        called_method_name: "PricingPlans::Assignment.assign_plan_to"
+      )
+    end
+
+    def self.remove_assignment_for(plan_owner)
+      LegacyPlanAssignmentApi.clear_override!(
+        plan_owner,
+        called_method_name: "PricingPlans::Assignment.remove_assignment_for"
+      )
+    end
+
     private
 
     def plan_exists_in_registry

data/lib/pricing_plans/plan_owner.rb

@@ -212,21 +212,49 @@ module PricingPlans
     end
 
     def has_plan_assignment?
+      pricing_plan_overridden?
+    end
+
+    def pricing_plan_overridden?
       return false unless respond_to?(:id) && id.present?
       Assignment.exists?(plan_owner_type: self.class.name, plan_owner_id: id)
     end
 
     def plan_assignment
+      pricing_plan_override
+    end
+
+    def pricing_plan_override
       return nil unless respond_to?(:id) && id.present?
       Assignment.find_by(plan_owner_type: self.class.name, plan_owner_id: id)
     end
 
+    def pricing_plan_override_source
+      pricing_plan_override&.source
+    end
+
+    def override_pricing_plan!(plan_key, source:)
+      PlanResolver.override_pricing_plan_for!(self, plan_key, source: source)
+    end
+
+    def clear_pricing_plan_override!
+      PlanResolver.clear_pricing_plan_override_for!(self)
+    end
+
     def assign_pricing_plan!(plan_key, source: "manual")
-      Assignment.assign_plan_to(self, plan_key, source: source)
+      LegacyPlanAssignmentApi.create_or_update_override!(
+        self,
+        plan_key,
+        source: source,
+        called_method_name: "assign_pricing_plan!"
+      )
     end
 
     def remove_pricing_plan!
-      Assignment.remove_assignment_for(self)
+      LegacyPlanAssignmentApi.clear_override!(
+        self,
+        called_method_name: "remove_pricing_plan!"
+      )
     end
 
     # Features

data/lib/pricing_plans/plan_resolution.rb

@@ -18,6 +18,10 @@ module PricingPlans
       source == :assignment
     end
 
+    def pricing_plan_overridden?
+      assignment?
+    end
+
     def subscription?
       source == :subscription
     end
@@ -34,12 +38,23 @@ module PricingPlans
       assignment&.source
     end
 
+    def pricing_plan_override
+      assignment
+    end
+
+    def pricing_plan_override_source
+      assignment_source
+    end
+
     # Extends Struct#to_h with derived fields.
     # Note: this preserves the raw plan / assignment / subscription objects.
     def to_h
       super.merge(
         plan_key: plan_key,
-        assignment_source: assignment_source
+        assignment_source: assignment_source,
+        pricing_plan_overridden: pricing_plan_overridden?,
+        pricing_plan_override: pricing_plan_override,
+        pricing_plan_override_source: pricing_plan_override_source
       )
     end
   end

data/lib/pricing_plans/plan_resolver.rb

@@ -18,11 +18,11 @@ module PricingPlans
       def resolution_for(plan_owner)
         log_debug "[PricingPlans::PlanResolver] resolution_for called for #{plan_owner.class.name}##{plan_owner.respond_to?(:id) ? plan_owner.id : 'N/A'}"
 
-        assignment = assignment_for(plan_owner)
+        assignment = pricing_plan_override_for(plan_owner)
         subscription = current_subscription_for(plan_owner)
 
         if assignment
-          log_debug "[PricingPlans::PlanResolver] Returning assignment-backed resolution: #{assignment.plan_key}"
+          log_debug "[PricingPlans::PlanResolver] Returning explicit-override resolution: #{assignment.plan_key}"
           return PlanResolution.new(
             plan: Registry.plan(assignment.plan_key),
             source: :assignment,
@@ -56,12 +56,32 @@ module PricingPlans
         )
       end
 
+      def override_pricing_plan_for!(plan_owner, plan_key, source:)
+        Assignment.create_or_update_pricing_plan_override_for!(
+          plan_owner,
+          plan_key,
+          source: source
+        )
+      end
+
+      def clear_pricing_plan_override_for!(plan_owner)
+        Assignment.clear_pricing_plan_override_for!(plan_owner)
+      end
+
       def assign_plan_manually!(plan_owner, plan_key, source: "manual")
-        Assignment.assign_plan_to(plan_owner, plan_key, source: source)
+        LegacyPlanAssignmentApi.create_or_update_override!(
+          plan_owner,
+          plan_key,
+          source: source,
+          called_method_name: "PricingPlans::PlanResolver.assign_plan_manually!"
+        )
       end
 
       def remove_manual_assignment!(plan_owner)
-        Assignment.remove_assignment_for(plan_owner)
+        LegacyPlanAssignmentApi.clear_override!(
+          plan_owner,
+          called_method_name: "PricingPlans::PlanResolver.remove_manual_assignment!"
+        )
       end
 
       private
@@ -71,8 +91,8 @@ module PricingPlans
         PaySupport.pay_available?
       end
 
-      def assignment_for(plan_owner)
-        log_debug "[PricingPlans::PlanResolver] Checking for manual assignment..."
+      def pricing_plan_override_for(plan_owner)
+        log_debug "[PricingPlans::PlanResolver] Checking for an explicit pricing plan override..."
         return nil unless plan_owner.respond_to?(:id)
 
         assignment = Assignment.find_by(
@@ -81,9 +101,9 @@ module PricingPlans
         )
 
         if assignment
-          log_debug "[PricingPlans::PlanResolver] Found manual assignment: #{assignment.plan_key}"
+          log_debug "[PricingPlans::PlanResolver] Found explicit pricing plan override: #{assignment.plan_key}"
         else
-          log_debug "[PricingPlans::PlanResolver] No manual assignment found"
+          log_debug "[PricingPlans::PlanResolver] No explicit pricing plan override found"
         end
 
         assignment

data/lib/pricing_plans/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PricingPlans
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/pricing_plans.rb

@@ -1,12 +1,24 @@
 # frozen_string_literal: true
 
 require_relative "pricing_plans/version"
+require "active_support/deprecation"
 require_relative "pricing_plans/engine" if defined?(Rails::Engine)
 
 module PricingPlans
   class Error < StandardError; end
   class ConfigurationError < Error; end
   class PlanNotFoundError < Error; end
+
+  class LegacyDefaultPlanAssignmentError < Error
+    attr_reader :configured_default_plan_key, :legacy_assignment_method_name
+
+    def initialize(message, configured_default_plan_key:, legacy_assignment_method_name:)
+      super(message)
+      @configured_default_plan_key = configured_default_plan_key.to_sym
+      @legacy_assignment_method_name = legacy_assignment_method_name
+    end
+  end
+
   class FeatureDenied < Error
     attr_reader :feature_key, :plan_owner
 
@@ -25,6 +37,7 @@ module PricingPlans
   autoload :DSL, "pricing_plans/dsl"
   autoload :IntegerRefinements, "pricing_plans/integer_refinements"
   autoload :PlanResolver, "pricing_plans/plan_resolver"
+  autoload :LegacyPlanAssignmentApi, "pricing_plans/legacy_plan_assignment_api"
   autoload :PaySupport, "pricing_plans/pay_support"
   autoload :LimitChecker, "pricing_plans/limit_checker"
   autoload :LimitableRegistry, "pricing_plans/limit_checker"
@@ -56,6 +69,13 @@ module PricingPlans
       @configuration ||= Configuration.new
     end
 
+    # A gem-specific deprecator lets host applications configure pricing_plans
+    # warnings independently and lets Rails include them in its deprecator
+    # collection.
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("0.6.0", "pricing_plans")
+    end
+
     def configure(&block)
       # Support both styles simultaneously inside the block:
       # - Bare DSL:   plan :free { ... }

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pricing_plans
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-08-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -98,6 +98,7 @@ files:
 - lib/pricing_plans/grace_manager.rb
 - lib/pricing_plans/integer_refinements.rb
 - lib/pricing_plans/job_guards.rb
+- lib/pricing_plans/legacy_plan_assignment_api.rb
 - lib/pricing_plans/limit_checker.rb
 - lib/pricing_plans/limitable.rb
 - lib/pricing_plans/models/assignment.rb
@@ -141,7 +142,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Define and enforce pricing plan limits (entitlements, quotas, feature gating)
   in your Rails SaaS