feat(products): attach rate cards directly to subscriptions

Sales-led subscriptions need rate cards attached and amended on the
subscription itself, without going through a plan. Snapshotted entries
also need sub-level phase amendments, since they are the subscription's
own copy of the plan's pricing.

Add SubscriptionProductItems::CreateService to attach a rate card
directly to a subscription (with a default indefinite phase), mirroring
the plan-side flow. Billing then follows the same path as snapshotted
items.

Generalize RatePhases::ReplaceService to accept either a plan or a
subscription entry as parent: plan-level phases stay locked once the
plan has subscriptions, while a subscription's own phases remain
editable (amendment flow).

Expose the REST endpoints under /api/v2/subscription_product_items
(index, show, create, nested rate_phases index/replace), with query
object, serializer, and the subscription_product_item API permission.

Author: rsempe

app/controllers/api/v2/subscription_product_items/rate_phases_controller.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Api
+  module V2
+    module SubscriptionProductItems
+      class RatePhasesController < Api::BaseController
+        def index
+          return not_found_error(resource: "subscription_product_item") unless subscription_product_item
+
+          render_rate_phases(subscription_product_item.rate_phases.order(:position))
+        end
+
+        def replace
+          return not_found_error(resource: "subscription_product_item") unless subscription_product_item
+
+          result = ::RatePhases::ReplaceService.call(
+            subscription_product_item:,
+            phases_params: replace_params
+          )
+
+          if result.success?
+            render_rate_phases(result.rate_phases)
+          else
+            render_error_response(result)
+          end
+        end
+
+        private
+
+        def subscription_product_item
+          @subscription_product_item ||= SubscriptionProductItem
+            .where(organization: current_organization)
+            .find_by(id: params[:subscription_product_item_id])
+        end
+
+        def replace_params
+          params
+            .permit(rate_phases: [
+              :position,
+              :name,
+              :billing_interval_cycle_count,
+              {rate_override: [
+                :rate_model,
+                :min_amount_cents,
+                :billing_interval_count,
+                :billing_interval_unit,
+                :pricing_unit_conversion_rate,
+                {rate_properties: {}}
+              ]}
+            ])
+            .to_h
+            .deep_symbolize_keys
+            .fetch(:rate_phases, [])
+        end
+
+        def render_rate_phases(rate_phases)
+          render(
+            json: ::CollectionSerializer.new(
+              rate_phases,
+              ::V1::RatePhaseSerializer,
+              collection_name: "rate_phases"
+            )
+          )
+        end
+
+        def resource_name
+          "subscription_product_item"
+        end
+      end
+    end
+  end
+end

app/controllers/api/v2/subscription_product_items_controller.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Api
+  module V2
+    class SubscriptionProductItemsController < Api::BaseController
+      def create
+        subscription = current_organization.subscriptions.find_by(id: create_params[:subscription_id])
+        result = ::SubscriptionProductItems::CreateService.call(
+          subscription:,
+          params: create_params.except(:subscription_id).to_h.deep_symbolize_keys
+        )
+
+        if result.success?
+          render_subscription_product_item(result.subscription_product_item)
+        else
+          render_error_response(result)
+        end
+      end
+
+      def show
+        subscription_product_item = subscription_product_items_scope.find_by(id: params[:id])
+
+        return not_found_error(resource: "subscription_product_item") unless subscription_product_item
+
+        render_subscription_product_item(subscription_product_item)
+      end
+
+      def index
+        result = ::SubscriptionProductItemsQuery.call(
+          organization: current_organization,
+          pagination: {
+            page: params[:page],
+            limit: params[:per_page] || PER_PAGE
+          },
+          filters: {subscription_id: params[:subscription_id]}
+        )
+
+        if result.success?
+          render(
+            json: ::CollectionSerializer.new(
+              result.subscription_product_items,
+              ::V1::SubscriptionProductItemSerializer,
+              collection_name: "subscription_product_items",
+              meta: pagination_metadata(result.subscription_product_items)
+            )
+          )
+        else
+          render_error_response(result)
+        end
+      end
+
+      private
+
+      def subscription_product_items_scope
+        SubscriptionProductItem.where(organization: current_organization)
+      end
+
+      def create_params
+        params.require(:subscription_product_item).permit(:subscription_id, :rate_card_code, :units, :started_at, :billing_anchor_date)
+      end
+
+      def render_subscription_product_item(subscription_product_item)
+        render(json: ::V1::SubscriptionProductItemSerializer.new(subscription_product_item, root_name: "subscription_product_item"))
+      end
+
+      def resource_name
+        "subscription_product_item"
+      end
+    end
+  end
+end

app/models/api_key.rb

@@ -8,6 +8,7 @@ class ApiKey < ApplicationRecord
     customer event fee invoice organization order order_form payment payment_receipt payment_request payment_method plan subscription lifetime_usage
     tax wallet wallet_transaction webhook_endpoint webhook_jwt_public_key invoice_custom_section
     billing_entity alert feature security_log quote product product_item rate_card plan_product_item
+    subscription_product_item
   ].freeze
 
   MODES = %w[read write].freeze

app/queries/subscription_product_items_query.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class SubscriptionProductItemsQuery < BaseQuery
+  Result = BaseResult[:subscription_product_items]
+  Filters = BaseFilters[:subscription_id]
+
+  def call
+    subscription_product_items = base_scope
+    subscription_product_items = with_subscription(subscription_product_items) if filters.subscription_id.present?
+    subscription_product_items = paginate(subscription_product_items)
+    subscription_product_items = apply_consistent_ordering(subscription_product_items)
+
+    result.subscription_product_items = subscription_product_items
+    result
+  end
+
+  private
+
+  def base_scope
+    SubscriptionProductItem.where(organization:)
+  end
+
+  def with_subscription(scope)
+    scope.where(subscription_id: filters.subscription_id)
+  end
+end

app/serializers/v1/subscription_product_item_serializer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module V1
+  class SubscriptionProductItemSerializer < ModelSerializer
+    def serialize
+      {
+        lago_id: model.id,
+        lago_subscription_id: model.subscription_id,
+        lago_rate_card_id: model.rate_card_id,
+        rate_card_code: model.rate_card.code,
+        units: model.units,
+        started_at: model.started_at.iso8601,
+        ended_at: model.ended_at&.iso8601,
+        billing_anchor_date: model.billing_anchor_date.iso8601,
+        next_billing_at: model.next_billing_at.iso8601,
+        rate_phases_count: model.rate_phases.count,
+        created_at: model.created_at.iso8601
+      }
+    end
+  end
+end

app/services/rate_phases/replace_service.rb

@@ -4,14 +4,15 @@ module RatePhases
   class ReplaceService < BaseService
     Result = BaseResult[:rate_phases]
 
-    def initialize(plan_product_item:, phases_params:)
+    def initialize(plan_product_item: nil, subscription_product_item: nil, phases_params: [])
       @plan_product_item = plan_product_item
+      @subscription_product_item = subscription_product_item
       @phases_params = Array.wrap(phases_params).map { |phase| phase.to_h.with_indifferent_access }
       super
     end
 
     def call
-      return result.not_found_failure!(resource: "plan_product_item") unless plan_product_item
+      return result.not_found_failure!(resource: "rate_phaseable") unless parent
       return result.single_validation_failure!(field: :rate_phases, error_code: "plan_locked") if plan_locked?
 
       sequence_failure = validate_sequence
@@ -21,7 +22,7 @@ def call
         discard_existing_phases
 
         result.rate_phases = ordered_params.map do |phase|
-          plan_product_item.rate_phases.create!(
+          parent.rate_phases.create!(
             organization:,
             position: phase[:position],
             name: phase[:name],
@@ -40,29 +41,35 @@ def call
 
     private
 
-    attr_reader :plan_product_item, :phases_params
+    attr_reader :plan_product_item, :subscription_product_item, :phases_params
+
+    def parent
+      plan_product_item || subscription_product_item
+    end
 
     def organization
-      plan_product_item.organization
+      parent.organization
     end
 
     def discard_existing_phases
-      existing_phases = plan_product_item.rate_phases.to_a
+      existing_phases = parent.rate_phases.to_a
       RateOverride.where(id: existing_phases.filter_map(&:rate_override_id)).discard_all!
-      plan_product_item.rate_phases.discard_all!
+      parent.rate_phases.discard_all!
     end
 
     def build_override(phase)
       return if phase[:rate_override].blank?
 
       RateOverrides::CreateService.call(
-        rate_card: plan_product_item.rate_card,
+        rate_card: parent.rate_card,
         params: phase[:rate_override]
       ).raise_if_error!.rate_override
     end
 
+    # Plan-level phases freeze once the plan has subscriptions; a subscription's
+    # own phases stay editable — they are the sub's copy (amendment flow).
     def plan_locked?
-      plan_product_item.plan.attached_to_subscriptions?
+      plan_product_item.present? && plan_product_item.plan.attached_to_subscriptions?
     end
 
     def ordered_params

app/services/subscription_product_items/create_service.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SubscriptionProductItems
+  # Attaches a rate card directly to a subscription (sales-led flow). Unlike
+  # plan snapshots, the entry is authored on the subscription itself; billing
+  # then follows the same path as snapshotted items.
+  class CreateService < BaseService
+    Result = BaseResult[:subscription_product_item]
+
+    def initialize(subscription:, params:)
+      @subscription = subscription
+      @params = params.to_h.with_indifferent_access
+      super
+    end
+
+    def call
+      return result.not_found_failure!(resource: "subscription") unless subscription
+
+      rate_card = organization.rate_cards.find_by(code: params[:rate_card_code])
+      return result.not_found_failure!(resource: "rate_card") unless rate_card
+
+      started_at = params[:started_at].presence || Time.current
+
+      ActiveRecord::Base.transaction do
+        subscription_product_item = subscription.subscription_product_items.create!(
+          organization:,
+          rate_card:,
+          units: params[:units],
+          started_at:,
+          billing_anchor_date: params[:billing_anchor_date].presence || started_at.to_date,
+          next_billing_at: started_at
+        )
+
+        RatePhases::CreateService.call!(subscription_product_item:, params: {position: 1})
+
+        result.subscription_product_item = subscription_product_item
+      end
+
+      result
+    rescue ActiveRecord::RecordInvalid => e
+      result.record_validation_failure!(record: e.record)
+    end
+
+    private
+
+    attr_reader :subscription, :params
+
+    def organization
+      subscription.organization
+    end
+  end
+end

config/routes.rb

@@ -48,6 +48,12 @@
           put "rate_phases", to: "rate_phases#replace"
         end
       end
+      resources :subscription_product_items, only: %i[index show create] do
+        scope module: :subscription_product_items do
+          get "rate_phases", to: "rate_phases#index"
+          put "rate_phases", to: "rate_phases#replace"
+        end
+      end
     end
   end
   resources :webhooks, only: [] do

spec/queries/subscription_product_items_query_spec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe SubscriptionProductItemsQuery, type: :query do
+  subject(:result) { described_class.call(organization:, pagination:, filters:) }
+
+  let(:organization) { create(:organization) }
+  let(:pagination) { nil }
+  let(:filters) { {} }
+
+  let(:customer) { create(:customer, organization:) }
+  let(:subscription) { create(:subscription, customer:, organization:) }
+  let!(:subscription_product_item) { create(:subscription_product_item, organization:, subscription:) }
+  let!(:other_subscription_product_item) { create(:subscription_product_item, organization:) }
+
+  it "returns all subscription product items of the organization" do
+    expect(result).to be_success
+    expect(result.subscription_product_items).to match_array([subscription_product_item, other_subscription_product_item])
+  end
+
+  context "when filtering by subscription_id" do
+    let(:filters) { {subscription_id: subscription.id} }
+
+    it "returns only the subscription's product items" do
+      expect(result.subscription_product_items).to eq([subscription_product_item])
+    end
+  end
+end