feat(api): serve subscriptions on the v2 API

## Context

The v1 subscription payload is built around the plan interval: amounts,
trial and current billing period. A product-catalog subscription has
none of that — it prices through its rate card entries, each carrying
its own billing cycle — so v2 consumers were reading legacy fields that
can only be null.

## Description

Add V2::SubscriptionSerializer (identity, status, lifecycle dates,
plan_code, and the subscription's rate card entries — embedded on show,
counted on index) and an Api::V2::SubscriptionsController serving index
and show. The catalog v2 routes now draw before the v1 fallback so the
first match wins for the paths they define; everything else on
/api/v2/subscriptions (create, terminate) still falls through to v1.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: rsempe

app/controllers/api/v2/subscriptions_controller.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Api
+  module V2
+    class SubscriptionsController < Api::BaseController
+      def index
+        filters = params.permit(:plan_code, :external_customer_id, :external_id, status: [])
+        filters[:status] = ["active"] if filters[:status].blank?
+
+        result = ::SubscriptionsQuery.call(
+          organization: current_organization,
+          pagination: {
+            page: params[:page],
+            limit: params[:per_page] || PER_PAGE
+          },
+          filters:
+        )
+
+        if result.success?
+          subscriptions = result.subscriptions.includes(:plan, customer: :billing_entity)
+
+          render(
+            json: ::CollectionSerializer.new(
+              subscriptions,
+              ::V2::SubscriptionSerializer,
+              collection_name: "subscriptions",
+              meta: pagination_metadata(subscriptions)
+            )
+          )
+        else
+          render_error_response(result)
+        end
+      end
+
+      def show
+        subscription = current_organization.subscriptions
+          .order("terminated_at DESC NULLS FIRST, started_at DESC")
+          .find_by(
+            external_id: params[:external_id],
+            status: params[:status] || :active
+          )
+        return not_found_error(resource: "subscription") unless subscription
+
+        render(
+          json: ::V2::SubscriptionSerializer.new(
+            subscription,
+            root_name: "subscription",
+            includes: %i[subscription_product_items]
+          )
+        )
+      end
+
+      private
+
+      def resource_name
+        "subscription"
+      end
+    end
+  end
+end

app/serializers/v2/subscription_serializer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module V2
+  # The v2 shape drops the plan-interval fields (amounts, billing periods,
+  # trial): a product-catalog subscription prices through its rate card
+  # entries, each carrying its own billing cycle.
+  class SubscriptionSerializer < ModelSerializer
+    def serialize
+      payload = {
+        lago_id: model.id,
+        external_id: model.external_id,
+        lago_customer_id: model.customer_id,
+        external_customer_id: model.customer.external_id,
+        name: model.name,
+        plan_code: model.plan.code,
+        status: model.status,
+        billing_time: model.billing_time,
+        subscription_at: model.subscription_at&.iso8601,
+        started_at: model.started_at&.iso8601,
+        ending_at: model.ending_at&.iso8601,
+        terminated_at: model.terminated_at&.iso8601,
+        canceled_at: model.canceled_at&.iso8601,
+        created_at: model.created_at.iso8601,
+        subscription_product_items_count: model.subscription_product_items.count
+      }
+
+      payload[:subscription_product_items] = subscription_product_items if include?(:subscription_product_items)
+
+      payload
+    end
+
+    private
+
+    def subscription_product_items
+      ::CollectionSerializer.new(
+        model.subscription_product_items,
+        ::V1::SubscriptionProductItemSerializer,
+        collection_name: "subscription_product_items"
+      ).serialize[:subscription_product_items]
+    end
+  end
+end

config/routes.rb

@@ -30,10 +30,8 @@
       draw(:shared_api)
     end
 
-    namespace :v2, module: :v1 do
-      draw(:shared_api)
-    end
-
+    # Catalog-specific v2 routes are drawn before the v1 fallback: for the
+    # paths defined here (e.g. GET /api/v2/subscriptions) the first match wins.
     namespace :v2 do
       resources :product_items, only: %i[index show create update destroy] do
         resources :filters, only: %i[index show create update destroy], controller: "product_items/filters"
@@ -54,6 +52,11 @@
           put "rate_phases", to: "rate_phases#replace"
         end
       end
+      resources :subscriptions, only: %i[index show], param: :external_id
+    end
+
+    namespace :v2, module: :v1 do
+      draw(:shared_api)
     end
   end
   resources :webhooks, only: [] do

spec/requests/api/v2/subscriptions_controller_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Api::V2::SubscriptionsController do
+  let(:organization) { create(:organization) }
+  let(:customer) { create(:customer, organization:) }
+  let(:plan) { create(:plan, organization:, pricing_type: "product_catalog") }
+  let(:subscription) { create(:subscription, customer:, plan:, organization:) }
+
+  describe "GET /api/v2/subscriptions" do
+    subject { get_with_token(organization, "/api/v2/subscriptions") }
+
+    before { create(:subscription_product_item, organization:, subscription:) }
+
+    include_examples "requires API permission", "subscription", "read"
+
+    it "returns subscriptions in the v2 shape" do
+      subject
+
+      expect(response).to have_http_status(:success)
+
+      result = json[:subscriptions].sole
+      expect(result[:lago_id]).to eq(subscription.id)
+      expect(result[:plan_code]).to eq(plan.code)
+      expect(result[:subscription_product_items_count]).to eq(1)
+      expect(result).not_to have_key(:current_billing_period_started_at)
+      expect(result).not_to have_key(:plan_amount_cents)
+    end
+  end
+
+  describe "GET /api/v2/subscriptions/:external_id" do
+    subject { get_with_token(organization, "/api/v2/subscriptions/#{subscription.external_id}") }
+
+    let!(:subscription_product_item) { create(:subscription_product_item, organization:, subscription:) }
+
+    include_examples "requires API permission", "subscription", "read"
+
+    it "returns the subscription with its rate card entries" do
+      subject
+
+      expect(response).to have_http_status(:success)
+      expect(json[:subscription][:lago_id]).to eq(subscription.id)
+      expect(json[:subscription][:subscription_product_items].sole[:lago_id]).to eq(subscription_product_item.id)
+    end
+
+    context "when it does not exist" do
+      subject { get_with_token(organization, "/api/v2/subscriptions/unknown") }
+
+      it "returns a not found error" do
+        subject
+
+        expect(response).to be_not_found_error("subscription")
+      end
+    end
+  end
+end