feat: handle payment error on trial

jono-booth · jono-booth · commit 54908d2b86e5 · 2025-10-29T12:54:47.000+02:00
diff --git a/enterprise_access/apps/api_client/license_manager_client.py b/enterprise_access/apps/api_client/license_manager_client.py
@@ -27,6 +27,56 @@ class LicenseManagerApiClient(BaseOAuthClient):
     customer_agreement_provisioning_endpoint = api_base_url + 'provisioning-admins/customer-agreement/'
     subscription_provisioning_endpoint = api_base_url + 'provisioning-admins/subscriptions/'
 
+    def list_subscriptions(self, enterprise_customer_uuid, current=None):
+        """
+        List subscription plans for an enterprise.
+
+        Returns a paginated DRF list response: { count, next, previous, results: [...] }
+        If current is True, returns only the current plan (results length 0 or 1).
+        """
+        try:
+            params = {
+                'enterprise_customer_uuid': enterprise_customer_uuid,
+            }
+            if current is not None:
+                params['current'] = 'true' if current else 'false'
+
+            response = self.client.get(
+                self.subscriptions_endpoint,
+                params=params,
+                timeout=settings.LICENSE_MANAGER_CLIENT_TIMEOUT,
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.HTTPError as exc:
+            logger.exception(
+                'Failed to list subscriptions for enterprise %s, response: %s, exc: %s',
+                enterprise_customer_uuid, safe_error_response_content(exc), exc,
+            )
+            raise
+
+    def update_subscription_plan(self, subscription_uuid, **payload):
+        """
+        Partially update a subscription plan by UUID.
+
+        Example payload: { 'is_active': False, 'change_reason': 'delayed_payment' }
+        """
+        endpoint = f"{self.subscription_provisioning_endpoint}{subscription_uuid}/"
+        try:
+            response = self.client.patch(
+                endpoint,
+                json=payload,
+                timeout=settings.LICENSE_MANAGER_CLIENT_TIMEOUT,
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.HTTPError as exc:
+            logger.exception(
+                'Failed to update subscription %s, payload=%s, response: %s, exc: %s',
+                subscription_uuid, payload, safe_error_response_content(exc), exc,
+            )
+            raise
+
     def get_subscription_overview(self, subscription_uuid):
         """
         Call license-manager API for data about a SubscriptionPlan.
diff --git a/enterprise_access/apps/api_client/tests/test_license_manager_client.py b/enterprise_access/apps/api_client/tests/test_license_manager_client.py
@@ -88,6 +88,49 @@ def test_create_customer_agreement(self, mock_oauth_client):
             json=expected_payload,
         )
 
+    @mock.patch('enterprise_access.apps.api_client.base_oauth.OAuthAPIClient', autospec=True)
+    def test_list_subscriptions_current_flag(self, mock_oauth_client):
+        mock_get = mock_oauth_client.return_value.get
+        mock_get.return_value.json.return_value = {'results': []}
+
+        lm_client = LicenseManagerApiClient()
+        enterprise_uuid = 'ec-uuid-123'
+
+        # current=True should set ?current=true
+        result = lm_client.list_subscriptions(enterprise_uuid, current=True)
+        self.assertEqual(result, {'results': []})
+
+        # Verify URL and params
+        expected_url = (
+            'http://license-manager.example.com'
+            '/api/v1/subscriptions/'
+        )
+        mock_get.assert_called_with(
+            expected_url,
+            params={'enterprise_customer_uuid': enterprise_uuid, 'current': 'true'},
+            timeout=settings.LICENSE_MANAGER_CLIENT_TIMEOUT,
+        )
+
+    @mock.patch('enterprise_access.apps.api_client.base_oauth.OAuthAPIClient', autospec=True)
+    def test_update_subscription_plan_patch(self, mock_oauth_client):
+        mock_patch = mock_oauth_client.return_value.patch
+        mock_patch.return_value.json.return_value = {'uuid': 'plan-uuid', 'is_active': False}
+
+        lm_client = LicenseManagerApiClient()
+        payload = {'is_active': False, 'change_reason': 'delayed_payment'}
+        result = lm_client.update_subscription_plan('plan-uuid', **payload)
+
+        self.assertEqual(result, mock_patch.return_value.json.return_value)
+        expected_url = (
+            'http://license-manager.example.com'
+            '/api/v1/provisioning-admins/subscriptions/plan-uuid/'
+        )
+        mock_patch.assert_called_once_with(
+            expected_url,
+            json=payload,
+            timeout=settings.LICENSE_MANAGER_CLIENT_TIMEOUT,
+        )
+
     @mock.patch('enterprise_access.apps.api_client.base_oauth.OAuthAPIClient', autospec=True)
     def test_create_subscription_plan(self, mock_oauth_client):
         mock_post = mock_oauth_client.return_value.post
diff --git a/enterprise_access/apps/customer_billing/stripe_event_handlers.py b/enterprise_access/apps/customer_billing/stripe_event_handlers.py
@@ -115,6 +115,117 @@ def link_event_data_to_checkout_intent(event, checkout_intent):
     event_data.save()
 
 
+def handle_pending_update(subscription_id: str, checkout_intent_id: int, pending_update):
+    """
+    Log pending update information for visibility.
+    Assumes a pending_update is present.
+    """
+    # TODO: take necessary action on the actual SubscriptionPlan and update the CheckoutIntent.
+    logger.warning(
+        "Subscription %s has pending update: %s. checkout_intent_id: %s",
+        subscription_id,
+        pending_update,
+        checkout_intent_id,
+    )
+
+
+def handle_trial_cancellation(checkout_intent: CheckoutIntent, checkout_intent_id: int, subscription_id: str, trial_end):
+    """
+    Send cancellation email for a trial subscription that has just transitioned to canceled.
+    Assumes caller validated status transition and presence of trial_end.
+    """
+    logger.info(
+        f"Subscription {subscription_id} transitioned to 'canceled'. "
+        f"Queuing trial cancellation email for checkout_intent_id={checkout_intent_id}"
+    )
+
+    send_trial_cancellation_email_task.delay(
+        checkout_intent_id=checkout_intent.id,
+        trial_end_timestamp=trial_end,
+    )
+
+
+def future_plans_of_current(current_plan_uuid: str, plans: list[dict]) -> list[dict]:
+    """
+    Return plans that are future renewals of the current plan, based on prior_renewals linkage.
+    """
+    def is_future_of_current(plan_dict):
+        if str(plan_dict.get('uuid')) == current_plan_uuid:
+            return False
+        for renewal in plan_dict.get('prior_renewals', []) or []:
+            if str(renewal.get('prior_subscription_plan_id')) == current_plan_uuid:
+                return True
+        return False
+
+    return [p for p in plans if is_future_of_current(p)]
+
+
+def cancel_all_future_plans(enterprise_uuid: str, reason: str = 'delayed_payment', subscription_id_for_logs: str | None = None) -> list[str]:
+    """
+    Deactivate (cancel) all future plans for the current plan of the given enterprise.
+
+    Returns list of deactivated plan UUIDs. Logs warnings/info for observability.
+    """
+    from enterprise_access.apps.api_client.license_manager_client import LicenseManagerApiClient
+
+    client = LicenseManagerApiClient()
+    deactivated = []
+    try:
+        current_list = client.list_subscriptions(enterprise_uuid, current=True)
+        current_results = (current_list or {}).get('results', [])
+        current_plan = current_results[0] if current_results else None
+        if not current_plan:
+            logger.warning(
+                "No current subscription plan found for enterprise %s when canceling future plans (subscription %s)",
+                enterprise_uuid, subscription_id_for_logs,
+            )
+            return deactivated
+
+        current_plan_uuid = str(current_plan.get('uuid'))
+
+        # Fetch all active plans for enterprise
+        all_list = client.list_subscriptions(enterprise_uuid)
+        all_plans = (all_list or {}).get('results', [])
+
+        future_plans = future_plans_of_current(current_plan_uuid, all_plans)
+        if not future_plans:
+            logger.info(
+                "No future plans to deactivate for enterprise %s (current plan %s) (subscription %s)",
+                enterprise_uuid, current_plan_uuid, subscription_id_for_logs,
+            )
+            return deactivated
+
+        # Deactivate all future plans
+        for future in future_plans:
+            future_uuid = future.get('uuid')
+            try:
+                client.update_subscription_plan(
+                    future_uuid,
+                    is_active=False,
+                    change_reason=reason,
+                )
+                deactivated.append(str(future_uuid))
+                logger.info(
+                    "Deactivated future plan %s for enterprise %s (reason=%s) (subscription %s)",
+                    future_uuid, enterprise_uuid, reason, subscription_id_for_logs,
+                )
+            except Exception as exc: # pylint: disable=broad-except
+                logger.exception(
+                    "Failed to deactivate future plan %s for enterprise %s (reason=%s): %s",
+                    future_uuid, enterprise_uuid, reason, exc,
+                )
+    except Exception as exc: # pylint: disable=broad-except
+        logger.exception(
+            "Unexpected error canceling future plans for enterprise %s (subscription %s): %s",
+            enterprise_uuid, subscription_id_for_logs, exc,
+        )
+
+    return deactivated
+
+
+
+
+
 class StripeEventHandler:
     """
     Container for Stripe event handler logic.
@@ -219,54 +330,40 @@ def subscription_updated(event: stripe.Event) -> None:
         Send cancellation notification email when a trial subscription is canceled.
         """
         subscription = event.data.object
-        pending_update = getattr(subscription, "pending_update", None)
-
-        checkout_intent_id = get_checkout_intent_id_from_subscription(
-            subscription
-        )
-        checkout_intent = get_checkout_intent_or_raise(
-            checkout_intent_id, event.id
-        )
+        checkout_intent_id = get_checkout_intent_id_from_subscription(subscription)
+        checkout_intent = get_checkout_intent_or_raise(checkout_intent_id, event.id)
         link_event_data_to_checkout_intent(event, checkout_intent)
 
+        # Pending update
+        pending_update = getattr(subscription, "pending_update", None)
         if pending_update:
-            # TODO: take necessary action on the actual SubscriptionPlan
-            # and update the CheckoutIntent.
-            logger.warning(
-                "Subscription %s has pending update: %s. checkout_intent_id: %s",
-                subscription.id,
-                pending_update,
-                get_checkout_intent_id_from_subscription(subscription),
-            )
+            handle_pending_update(subscription.id, checkout_intent_id, pending_update)
 
-        # Handle trial subscription cancellation
-        # Check if status changed to canceled to avoid duplicate emails
+        # Trial cancellation transition
         current_status = subscription.get("status")
-        if current_status == "canceled":
-            prior_status = getattr(checkout_intent.previous_summary(event), 'subscription_status', None)
-
-            # Only send email if status changed from non-canceled to canceled
-            if prior_status != 'canceled':
-                trial_end = subscription.get("trial_end")
-                if trial_end:
-                    logger.info(
-                        f"Subscription {subscription.id} status changed from '{prior_status}' to 'canceled'. "
-                        f"Queuing trial cancellation email for checkout_intent_id={checkout_intent_id}"
-                    )
-
-                    send_trial_cancellation_email_task.delay(
-                        checkout_intent_id=checkout_intent.id,
-                        trial_end_timestamp=trial_end,
-                    )
-                else:
-                    logger.info(
-                        f"Subscription {subscription.id} canceled but has no trial_end, skipping cancellation email"
-                    )
+        prior_status = getattr(checkout_intent.previous_summary(event), 'subscription_status', None)
+        if current_status == "canceled" and prior_status != "canceled":
+            trial_end = subscription.get("trial_end")
+            if trial_end:
+                handle_trial_cancellation(checkout_intent, checkout_intent_id, subscription.id, trial_end)
+
+        # Past due transition
+        if current_status == "past_due" and prior_status != "past_due":
+            enterprise_uuid = checkout_intent.enterprise_uuid
+            if enterprise_uuid:
+                cancel_all_future_plans(
+                    enterprise_uuid=enterprise_uuid,
+                    reason='delayed_payment',
+                    subscription_id_for_logs=subscription.id,
+                )
             else:
-                logger.info(
-                    f"Subscription {subscription.id} already canceled (status unchanged), skipping cancellation email"
+                logger.error(
+                    "Cannot deactivate future plans for subscription %s: missing enterprise_uuid on CheckoutIntent %s",
+                    subscription.id, checkout_intent.id,
                 )
 
+
+
     @on_stripe_event("customer.subscription.deleted")
     @staticmethod
     def subscription_deleted(event: stripe.Event) -> None:
diff --git a/enterprise_access/apps/customer_billing/tests/test_stripe_event_handlers.py b/enterprise_access/apps/customer_billing/tests/test_stripe_event_handlers.py
@@ -16,7 +16,11 @@
 from enterprise_access.apps.core.tests.factories import UserFactory
 from enterprise_access.apps.customer_billing.constants import CheckoutIntentState
 from enterprise_access.apps.customer_billing.models import CheckoutIntent, StripeEventData
-from enterprise_access.apps.customer_billing.stripe_event_handlers import StripeEventHandler
+from enterprise_access.apps.customer_billing.stripe_event_handlers import (
+    StripeEventHandler,
+    future_plans_of_current,
+    cancel_all_future_plans,
+)
 
 
 class AttrDict(dict):
@@ -277,3 +281,43 @@ def test_subscription_updated_skips_email_when_no_trial_end(self):
         ) as mock_task:
             StripeEventHandler.dispatch(mock_event)
             mock_task.delay.assert_not_called()
+
+    def test_future_plans_of_current_selects_children(self):
+        """future_plans_of_current returns plans whose prior_renewals link to current plan."""
+        current_uuid = "1111-aaaa"
+        plans = [
+            {"uuid": current_uuid, "prior_renewals": []},
+            {"uuid": "2222-bbbb", "prior_renewals": [{"prior_subscription_plan_id": current_uuid}]},
+            {"uuid": "3333-cccc", "prior_renewals": [{"prior_subscription_plan_id": current_uuid}]},
+            {"uuid": "4444-dddd", "prior_renewals": []},
+        ]
+
+        result = future_plans_of_current(current_uuid, plans)
+        self.assertEqual({p["uuid"] for p in result}, {"2222-bbbb", "3333-cccc"})
+
+    @mock.patch("enterprise_access.apps.customer_billing.stripe_event_handlers.LicenseManagerApiClient")
+    def test_cancel_all_future_plans_deactivates_all(self, MockClient):
+        """cancel_all_future_plans patches all future plans and returns their uuids."""
+        enterprise_uuid = "ent-123"
+        current_uuid = "1111-aaaa"
+        future1 = {"uuid": "2222-bbbb", "prior_renewals": [{"prior_subscription_plan_id": current_uuid}]}
+        future2 = {"uuid": "3333-cccc", "prior_renewals": [{"prior_subscription_plan_id": current_uuid}]}
+
+        mock_client = MockClient.return_value
+        # list_subscriptions(current=True)
+        mock_client.list_subscriptions.side_effect = [
+            {"results": [{"uuid": current_uuid}]},  # current=True response
+            {"results": [
+                {"uuid": current_uuid, "prior_renewals": []},
+                future1,
+                future2,
+            ]},  # all plans response
+        ]
+
+        deactivated = cancel_all_future_plans(enterprise_uuid, reason="delayed_payment", subscription_id_for_logs="sub-1")
+
+        # Should have patched both future plans
+        self.assertEqual(set(deactivated), {"2222-bbbb", "3333-cccc"})
+        self.assertEqual(mock_client.update_subscription_plan.call_count, 2)
+        mock_client.update_subscription_plan.assert_any_call("2222-bbbb", is_active=False, change_reason="delayed_payment")
+        mock_client.update_subscription_plan.assert_any_call("3333-cccc", is_active=False, change_reason="delayed_payment")
