fix(subscriptions): validate seat bounds on seat→seat product switches (#14198)

Co-authored-by: detail-app[bot] <180357370+detail-app[bot]@users.noreply.github.com>

Author: detail-app[bot]

server/polar/subscription/service.py

@@ -276,40 +276,70 @@ def __init__(
 
 class BelowMinimumSeats(PolarRequestValidationError):
     def __init__(
-        self, subscription: Subscription, minimum_seats: int, requested_seats: int
+        self,
+        subscription: Subscription,
+        minimum_seats: int,
+        requested_seats: int,
+        *,
+        product_id: uuid.UUID | None = None,
     ) -> None:
         self.subscription = subscription
         self.minimum_seats = minimum_seats
         self.requested_seats = requested_seats
-        super().__init__(
-            [
-                {
-                    "type": "value_error",
-                    "loc": ("body", "seats"),
-                    "msg": f"Minimum {minimum_seats} seats required.",
-                    "input": requested_seats,
-                }
-            ]
-        )
+        # A product change keeps the live seat count, so the offending input is
+        # the target product, not a submitted seat count.
+        error: ValidationError
+        if product_id is not None:
+            error = {
+                "type": "value_error",
+                "loc": ("body", "product_id"),
+                "msg": (
+                    f"Current seat count of {requested_seats} is below the "
+                    f"minimum of {minimum_seats} seats for this product."
+                ),
+                "input": product_id,
+            }
+        else:
+            error = {
+                "type": "value_error",
+                "loc": ("body", "seats"),
+                "msg": f"Minimum {minimum_seats} seats required.",
+                "input": requested_seats,
+            }
+        super().__init__([error])
 
 
 class AboveMaximumSeats(PolarRequestValidationError):
     def __init__(
-        self, subscription: Subscription, maximum_seats: int, requested_seats: int
+        self,
+        subscription: Subscription,
+        maximum_seats: int,
+        requested_seats: int,
+        *,
+        product_id: uuid.UUID | None = None,
     ) -> None:
         self.subscription = subscription
         self.maximum_seats = maximum_seats
         self.requested_seats = requested_seats
-        super().__init__(
-            [
-                {
-                    "type": "value_error",
-                    "loc": ("body", "seats"),
-                    "msg": f"Maximum {maximum_seats} seats allowed.",
-                    "input": requested_seats,
-                }
-            ]
-        )
+        error: ValidationError
+        if product_id is not None:
+            error = {
+                "type": "value_error",
+                "loc": ("body", "product_id"),
+                "msg": (
+                    f"Current seat count of {requested_seats} is above the "
+                    f"maximum of {maximum_seats} seats for this product."
+                ),
+                "input": product_id,
+            }
+        else:
+            error = {
+                "type": "value_error",
+                "loc": ("body", "seats"),
+                "msg": f"Maximum {maximum_seats} seats allowed.",
+                "input": requested_seats,
+            }
+        super().__init__([error])
 
 
 class NotAUnitBasedSubscription(PolarRequestValidationError):
@@ -1945,7 +1975,7 @@ async def update_product(
                 proration_behavior = organization.proration_behavior
 
             is_initial_seat_transition = self._promote_seats_for_seat_transition(
-                subscription, currency_prices, proration_behavior
+                subscription, currency_prices, proration_behavior, product_id
             )
             self._promote_units_for_unit_transition(
                 subscription, currency_prices, proration_behavior, product_id
@@ -3165,7 +3195,7 @@ async def _compute_change_preview(
                 allowed_visibilities=allowed_visibilities,
             )
             self._promote_seats_for_seat_transition(
-                subscription, currency_prices, proration_behavior
+                subscription, currency_prices, proration_behavior, product_id
             )
             self._promote_units_for_unit_transition(
                 subscription, currency_prices, proration_behavior, product_id
@@ -3283,22 +3313,36 @@ def _promote_seats_for_seat_transition(
         subscription: Subscription,
         currency_prices: PriceSet,
         proration_behavior: SubscriptionProrationBehavior,
+        product_id: uuid.UUID,
     ) -> bool:
         """Promote `subscription.seats` to the new product's first seat-price tier
         minimum, so the proration debit and `apply_update`'s product-branch rebuild
         both see a valid seat count. `next_period` is blocked because the post-apply
         seat auto-claim has to run immediately, or the billing customer loses benefit
         access. Returns whether this was a non-seat → seat transition.
         """
-        if any(is_seat_price(price) for price in subscription.prices):
-            return False
-
         seat_price = next(
             (price for price in currency_prices if is_seat_price(price)), None
         )
         if seat_price is None:
             return False
 
+        if any(is_seat_price(price) for price in subscription.prices):
+            seats = subscription.seats
+            if seats is None:
+                return False
+            minimum_seats = seat_price.get_minimum_seats()
+            if seats < minimum_seats:
+                raise BelowMinimumSeats(
+                    subscription, minimum_seats, seats, product_id=product_id
+                )
+            maximum_seats = seat_price.get_maximum_seats()
+            if maximum_seats is not None and seats > maximum_seats:
+                raise AboveMaximumSeats(
+                    subscription, maximum_seats, seats, product_id=product_id
+                )
+            return False
+
         if proration_behavior == SubscriptionProrationBehavior.next_period:
             raise PolarRequestValidationError(
                 [

server/tests/customer_portal/endpoints/test_subscription.py

@@ -4,10 +4,12 @@
 from httpx import AsyncClient
 
 from polar.enums import SubscriptionRecurringInterval
+from polar.kit.currency import PresentmentCurrency
 from polar.kit.utils import utc_now
 from polar.kit.visibility import Visibility
 from polar.models import Customer, Member, Organization, Product, Subscription
 from polar.models.order import OrderStatus
+from polar.models.product_price import ProductPriceSeatUnit
 from polar.models.subscription import SubscriptionStatus
 from polar.postgres import AsyncSession
 from tests.fixtures.auth import (
@@ -24,6 +26,7 @@
     create_order,
     create_payment_method,
     create_product,
+    create_subscription_with_seats,
     set_product_benefits,
 )
 
@@ -241,6 +244,53 @@ async def test_update_plan_not_allowed(
         assert error["error"] == "UpdateSubscriptionPlanNotAllowed"
         assert "not allowed" in error["detail"].lower()
 
+    @pytest.mark.auth(CUSTOMER_AUTH_SUBJECT)
+    async def test_seat_to_seat_below_target_minimum_returns_422_on_product_id(
+        self,
+        client: AsyncClient,
+        save_fixture: SaveFixture,
+        organization: Organization,
+        customer: Customer,
+    ) -> None:
+        old_seat_product = await create_product(
+            save_fixture,
+            organization=organization,
+            recurring_interval=SubscriptionRecurringInterval.month,
+            prices=[("seat", 1000, "usd")],
+        )
+        new_seat_product = await create_product(
+            save_fixture,
+            organization=organization,
+            recurring_interval=SubscriptionRecurringInterval.month,
+            prices=[],
+        )
+        new_seat_price = ProductPriceSeatUnit(
+            price_currency=PresentmentCurrency.usd,
+            seat_tiers={
+                "tiers": [
+                    {"min_seats": 5, "max_seats": None, "price_per_seat": 2000},
+                ],
+            },
+            product=new_seat_product,
+        )
+        await save_fixture(new_seat_price)
+        new_seat_product.prices.append(new_seat_price)
+        await save_fixture(new_seat_product)
+
+        subscription = await create_subscription_with_seats(
+            save_fixture, product=old_seat_product, customer=customer, seats=3
+        )
+
+        response = await client.patch(
+            f"/v1/customer-portal/subscriptions/{subscription.id}",
+            json={"product_id": str(new_seat_product.id)},
+        )
+
+        assert response.status_code == 422
+        error = response.json()
+        assert error["detail"][0]["loc"] == ["body", "product_id"]
+        assert "below the minimum of 5 seats" in error["detail"][0]["msg"]
+
 
 @pytest.mark.asyncio
 class TestCustomerSubscriptionUpdateUnknownFields:

server/tests/subscription/test_endpoints.py

@@ -6,7 +6,8 @@
 from httpx import AsyncClient
 
 from polar.auth.scope import Scope
-from polar.enums import SubscriptionRecurringInterval
+from polar.enums import SubscriptionProrationBehavior, SubscriptionRecurringInterval
+from polar.kit.currency import PresentmentCurrency
 from polar.kit.utils import utc_now
 from polar.kit.visibility import Visibility
 from polar.models import (
@@ -18,6 +19,7 @@
 )
 from polar.models.customer_seat import SeatStatus
 from polar.models.order import OrderStatus
+from polar.models.product_price import ProductPriceSeatUnit
 from polar.models.subscription import CustomerCancellationReason, SubscriptionStatus
 from polar.postgres import AsyncSession
 from tests.fixtures.auth import AuthSubjectFixture
@@ -548,6 +550,107 @@ async def test_valid(
         updated_subscription = response.json()
         assert updated_subscription["product"]["id"] == str(product_second.id)
 
+    @pytest.mark.auth
+    async def test_seat_to_seat_below_target_minimum_returns_422_on_product_id(
+        self,
+        client: AsyncClient,
+        save_fixture: SaveFixture,
+        organization: Organization,
+        user_organization: UserOrganization,
+        customer: Customer,
+    ) -> None:
+        old_seat_product = await create_product(
+            save_fixture,
+            organization=organization,
+            recurring_interval=SubscriptionRecurringInterval.month,
+            prices=[("seat", 1000, "usd")],
+        )
+        new_seat_product = await create_product(
+            save_fixture,
+            organization=organization,
+            recurring_interval=SubscriptionRecurringInterval.month,
+            prices=[],
+        )
+        new_seat_price = ProductPriceSeatUnit(
+            price_currency=PresentmentCurrency.usd,
+            seat_tiers={
+                "tiers": [
+                    {"min_seats": 5, "max_seats": None, "price_per_seat": 2000},
+                ],
+            },
+            product=new_seat_product,
+        )
+        await save_fixture(new_seat_price)
+        new_seat_product.prices.append(new_seat_price)
+        await save_fixture(new_seat_product)
+
+        subscription = await create_subscription_with_seats(
+            save_fixture, product=old_seat_product, customer=customer, seats=3
+        )
+
+        response = await client.patch(
+            f"/v1/subscriptions/{subscription.id}",
+            json={"product_id": str(new_seat_product.id)},
+        )
+
+        assert response.status_code == 422
+        error = response.json()
+        assert error["detail"][0]["loc"] == ["body", "product_id"]
+        assert "below the minimum of 5 seats" in error["detail"][0]["msg"]
+        assert error["detail"][0]["input"] == str(new_seat_product.id)
+
+    @pytest.mark.auth
+    async def test_seat_to_seat_above_target_maximum_returns_422_on_product_id(
+        self,
+        client: AsyncClient,
+        save_fixture: SaveFixture,
+        organization: Organization,
+        user_organization: UserOrganization,
+        customer: Customer,
+    ) -> None:
+        old_seat_product = await create_product(
+            save_fixture,
+            organization=organization,
+            recurring_interval=SubscriptionRecurringInterval.month,
+            prices=[("seat", 1000, "usd")],
+        )
+        new_seat_product = await create_product(
+            save_fixture,
+            organization=organization,
+            recurring_interval=SubscriptionRecurringInterval.month,
+            prices=[],
+        )
+        new_seat_price = ProductPriceSeatUnit(
+            price_currency=PresentmentCurrency.usd,
+            seat_tiers={
+                "tiers": [
+                    {"min_seats": 1, "max_seats": 10, "price_per_seat": 1000},
+                ],
+            },
+            product=new_seat_product,
+        )
+        await save_fixture(new_seat_price)
+        new_seat_product.prices.append(new_seat_price)
+        await save_fixture(new_seat_product)
+
+        subscription = await create_subscription_with_seats(
+            save_fixture, product=old_seat_product, customer=customer, seats=50
+        )
+
+        response = await client.patch(
+            f"/v1/subscriptions/{subscription.id}",
+            json={
+                "product_id": str(new_seat_product.id),
+                "proration_behavior": SubscriptionProrationBehavior.next_period.value,
+            },
+        )
+
+        assert response.status_code == 422
+        error = response.json()
+        assert error["detail"][0]["loc"] == ["body", "product_id"]
+        assert "above the maximum of 10 seats" in error["detail"][0]["msg"]
+        assert error["detail"][0]["input"] == str(new_seat_product.id)
+
 
 @pytest.mark.asyncio
 class TestSubscriptionUpdateMetadata: