WIP: add email task

Author: jono-booth

enterprise_access/apps/customer_billing/stripe_event_handlers.py

@@ -9,7 +9,10 @@
 
 from enterprise_access.apps.customer_billing.models import CheckoutIntent, StripeEventData
 from enterprise_access.apps.customer_billing.stripe_event_types import StripeEventType
-from enterprise_access.apps.customer_billing.tasks import send_trial_cancellation_email_task
+from enterprise_access.apps.customer_billing.tasks import (
+    send_trial_cancellation_email_task,
+    send_billing_error_email_task,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -349,6 +352,16 @@ def subscription_updated(event: stripe.Event) -> None:
 
         # Past due transition
         if current_status == "past_due" and prior_status != "past_due":
+            # Fire billing error email to enterprise admins
+            try:
+                send_billing_error_email_task.delay(checkout_intent_id=checkout_intent.id)
+            except Exception as exc:  # pylint: disable=broad-exception-caught
+                logger.exception(
+                    "Failed to enqueue billing error email for CheckoutIntent %s: %s",
+                    checkout_intent.id,
+                    str(exc),
+                )
+
             enterprise_uuid = checkout_intent.enterprise_uuid
             if enterprise_uuid:
                 cancel_all_future_plans(

enterprise_access/apps/customer_billing/tasks.py

@@ -288,3 +288,110 @@ def send_trial_cancellation_email_task(
             str(exc),
         )
         raise
+
+
+@shared_task(base=LoggedTaskWithRetry)
+def send_billing_error_email_task(checkout_intent_id: int):
+    """
+    Send Braze email notification when a subscription encounters a billing error
+    (e.g., transitions to past_due).
+
+    The email includes a link to the Stripe billing portal so admins can fix their
+    payment method and restart the subscription.
+
+    Args:
+        checkout_intent_id (int): ID of the CheckoutIntent record
+    """
+    try:
+        checkout_intent = CheckoutIntent.objects.get(id=checkout_intent_id)
+    except CheckoutIntent.DoesNotExist:
+        logger.error(
+            "Billing error email not sent: CheckoutIntent %s not found",
+            checkout_intent_id,
+        )
+        return
+
+    enterprise_slug = checkout_intent.enterprise_slug
+    logger.info(
+        "Sending billing error email for CheckoutIntent %s (enterprise slug: %s)",
+        checkout_intent_id,
+        enterprise_slug,
+    )
+
+    braze_client = BrazeApiClient()
+    lms_client = LmsApiClient()
+
+    # Fetch enterprise customer data to get admin users
+    try:
+        enterprise_data = lms_client.get_enterprise_customer_data(
+            enterprise_customer_slug=enterprise_slug
+        )
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        logger.error(
+            "Failed to fetch enterprise data for slug %s: %s. Cannot send billing error email.",
+            enterprise_slug,
+            str(exc),
+        )
+        return
+
+    admin_users = enterprise_data.get("admin_users", [])
+
+    if not admin_users:
+        logger.error(
+            "Billing error email not sent: No admin users found for enterprise slug %s. "
+            "Verify admin setup in LMS.",
+            enterprise_slug,
+        )
+        return
+
+    # Generate Stripe billing portal URL for fixing payment method
+    portal_url = _get_billing_portal_url(checkout_intent)
+
+    braze_trigger_properties = {
+        "restart_subscription_url": portal_url,
+    }
+
+    # Create Braze recipients for all admin users
+    recipients = []
+    for admin in admin_users:
+        try:
+            admin_email = admin["email"]
+            recipient = braze_client.create_braze_recipient(
+                user_email=admin_email,
+                lms_user_id=admin.get("lms_user_id"),
+            )
+            recipients.append(recipient)
+        except Exception as exc:  # pylint: disable=broad-exception-caught
+            logger.warning(
+                "Failed to create Braze recipient for admin email %s: %s",
+                admin_email,
+                str(exc),
+            )
+
+    if not recipients:
+        logger.error(
+            "Billing error email not sent: No valid Braze recipients created for enterprise slug %s. "
+            "Check admin email errors above.",
+            enterprise_slug,
+        )
+        return
+
+    # Send the campaign message to all admin recipients
+    try:
+        braze_client.send_campaign_message(
+            settings.BRAZE_BILLING_ERROR_CAMPAIGN,
+            recipients=recipients,
+            trigger_properties=braze_trigger_properties,
+        )
+        logger.info(
+            "Successfully sent billing error emails for CheckoutIntent %s to %d recipients",
+            checkout_intent_id,
+            len(recipients),
+        )
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        logger.exception(
+            "Braze API error: Failed to send billing error email for CheckoutIntent %s. Error: %s",
+            checkout_intent_id,
+            str(exc),
+        )
+        raise

enterprise_access/apps/customer_billing/tests/test_stripe_event_handlers.py

@@ -282,6 +282,44 @@ def test_subscription_updated_skips_email_when_no_trial_end(self):
             StripeEventHandler.dispatch(mock_event)
             mock_task.delay.assert_not_called()
 
+    @mock.patch(
+        "enterprise_access.apps.customer_billing.stripe_event_handlers.cancel_all_future_plans"
+    )
+    @mock.patch(
+        "enterprise_access.apps.customer_billing.stripe_event_handlers.send_billing_error_email_task"
+    )
+    @mock.patch.object(CheckoutIntent, "previous_summary")
+    def test_subscription_updated_past_due_cancels_future_plans(
+        self, mock_prev_summary, mock_send_billing_error, mock_cancel
+    ):
+        """Past-due transition triggers cancel_all_future_plans with expected args."""
+        subscription_id = "sub_test_past_due_123"
+        subscription_data = {
+            "id": subscription_id,
+            "status": "past_due",
+            "metadata": self._create_mock_stripe_subscription(self.checkout_intent.id),
+        }
+
+        # Simulate prior status was not past_due
+        mock_prev_summary.return_value = AttrDict({"subscription_status": "active"})
+
+        mock_event = self._create_mock_stripe_event(
+            "customer.subscription.updated", subscription_data
+        )
+
+        StripeEventHandler.dispatch(mock_event)
+
+        mock_cancel.assert_called_once()
+        mock_send_billing_error.delay.assert_called_once_with(checkout_intent_id=self.checkout_intent.id)
+        _, kwargs = mock_cancel.call_args
+        self.assertEqual(
+            kwargs["enterprise_uuid"], self.checkout_intent.enterprise_uuid
+        )
+        self.assertEqual(kwargs["reason"], "delayed_payment")
+        self.assertEqual(
+            kwargs["subscription_id_for_logs"], subscription_id
+        )
+
     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"