feat: upcoming invoice amount due

Author: iloveagent57

enterprise_access/apps/api/v1/views/customer_billing.py

@@ -517,3 +517,14 @@ def list(self, request, *args, **kwargs):
         Lists ``StripeEventSummary`` records, filtered by given subscription plan uuid.
         """
         return super().list(request, *args, **kwargs)
+
+    @action(
+        detail=False,
+        methods=['get'],
+        url_path='first-invoice-upcoming-amount-due',
+    )
+    def first_invoice_upcoming_amount_due(self, request, *args, **kwargs):
+        summary = self.get_queryset().filter(event_type='customer.subscription.created').first()
+        return Response({
+            'upcoming_invoice_amount_due': summary.upcoming_invoice_amount_due,
+        }, content_type='application/json')

enterprise_access/apps/customer_billing/migrations/0017_upcoming_invoice_amount_due.py

@@ -0,0 +1,18 @@
+# Generated by Django 4.2.25 on 2025-10-31 18:26
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('customer_billing', '0016_alter_checkoutintent_uuid_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='stripeeventsummary',
+            name='upcoming_invoice_amount_due',
+            field=models.IntegerField(blank=True, help_text='Upcoming invoice amount due related to this event/subscription', null=True),
+        ),
+    ]

enterprise_access/apps/customer_billing/models.py

@@ -23,6 +23,7 @@
 from simple_history.models import HistoricalRecords
 from simple_history.utils import bulk_update_with_history
 
+from enterprise_access.apps.customer_billing import stripe_api
 from enterprise_access.apps.customer_billing.constants import ALLOWED_CHECKOUT_INTENT_STATE_TRANSITIONS
 
 from .constants import INTENT_RESERVATION_DURATION_MINUTES, CheckoutIntentState
@@ -736,6 +737,11 @@ class StripeEventSummary(TimeStampedModel):
         blank=True,
         help_text='Currency of the invoice'
     )
+    upcoming_invoice_amount_due = models.IntegerField(
+        null=True,
+        blank=True,
+        help_text='Upcoming invoice amount due related to this event/subscription'
+    )
 
     class Meta:
         db_table = 'customer_billing_stripe_event_summary'
@@ -824,6 +830,34 @@ def populate_with_summary_data(self):
                 if self.invoice_unit_amount is None:
                     self.invoice_unit_amount = int(self.invoice_unit_amount_decimal)
 
+    def update_upcoming_invoice_amount_due(self):
+        """
+        Updates the `amount_due` of this record from the first upcoming invoice
+        associated with this customer's subscription.
+        """
+        self.checkout_intent = CheckoutIntent.objects.first()
+        if not self.checkout_intent:
+            logger.warning(
+                'Cannot update with upcoming invoice for event %s, no checkout intent exists',
+                self.event_id,
+            )
+            return
+        stripe_subscription_id = self.stripe_subscription_id
+        stripe_customer_id = self.checkout_intent.stripe_customer_id
+
+        if not (stripe_subscription_id and stripe_customer_id):
+            logger.warning('Cannot update with upcoming invoice for event %s', self.event_id)
+            return
+
+        # Now call the stripe invoice upcoming API
+        upcoming_invoice = stripe_api.upcoming_invoice(stripe_customer_id, stripe_subscription_id)
+        if not upcoming_invoice:
+            logger.warning('No upcoming invoice exists for event %s', self.event_id)
+            return
+
+        self.upcoming_invoice_amount_due = upcoming_invoice.amount_due
+        self.save(update_fields=['upcoming_invoice_amount_due'])
+
     @staticmethod
     def _timestamp_to_datetime(timestamp):
         """Convert Unix timestamp to Django datetime."""

enterprise_access/apps/customer_billing/stripe_api.py

@@ -240,3 +240,15 @@ def get_stripe_trialing_subscription(
         limit=1,
     )
     return subscription_list.data[0] if subscription_list.data else None
+
+
+@stripe_cache()
+def upcoming_invoice(stripe_customer_id, stripe_subscription_id):
+    """
+    https://docs.stripe.com/changelog/basil/2025-03-31/invoice-preview-api-deprecations
+    https://docs.stripe.com/api/invoices/create_preview?architecture-style=resources
+    """
+    return stripe.Invoice.create_preview(
+        customer=stripe_customer_id,
+        subscription=stripe_subscription_id,
+    )

enterprise_access/apps/customer_billing/stripe_event_handlers.py

@@ -7,7 +7,7 @@
 
 import stripe
 
-from enterprise_access.apps.customer_billing.models import CheckoutIntent, StripeEventData
+from enterprise_access.apps.customer_billing.models import CheckoutIntent, StripeEventData, StripeEventSummary
 from enterprise_access.apps.customer_billing.stripe_event_types import StripeEventType
 from enterprise_access.apps.customer_billing.tasks import send_trial_cancellation_email_task
 
@@ -210,6 +210,9 @@ def subscription_created(event: stripe.Event) -> None:
         except stripe.StripeError as e:
             logger.error(f'Failed to enable pending updates for subscription {subscription.id}: {e}')
 
+        summary = StripeEventSummary.objects.get(event_id=event.id)
+        summary.update_upcoming_invoice_amount_due()
+
     @on_stripe_event('customer.subscription.updated')
     @staticmethod
     def subscription_updated(event: stripe.Event) -> None: