[PM-30908]Correct Premium subscription status handling (#6877)

* Implement the correct changes

* failing test has been removed

* Add unit testing and logs

* Resolve the pr comment on missed requirements

* fix the lint error

* resolve the build lint

* Fix the failing test

* Fix the failing test

* Add the IncompleteExpired status

* resolve the lint error

* Fix the build lint error

* Implement the IncompleteExpired flow

Author: cyprain-okeke

src/Api/Billing/Controllers/VNext/AccountBillingVNextController.cs

@@ -102,7 +102,7 @@ public async Task<IResult> GetSubscriptionAsync(
         [BindNever] User user)
     {
         var subscription = await getBitwardenSubscriptionQuery.Run(user);
-        return TypedResults.Ok(subscription);
+        return subscription == null ? TypedResults.NotFound() : TypedResults.Ok(subscription);
     }
 
     [HttpPost("subscription/reinstate")]

src/Billing/Services/Implementations/PaymentMethodAttachedHandler.cs

@@ -104,35 +104,56 @@ await _stripeFacade.UpdateSubscription(invoicedProviderSubscription.Id,
         var unpaidSubscriptions = subscriptions?.Data.Where(subscription =>
             subscription.Status == StripeConstants.SubscriptionStatus.Unpaid).ToList();
 
-        if (unpaidSubscriptions == null || unpaidSubscriptions.Count == 0)
+        var incompleteSubscriptions = subscriptions?.Data.Where(subscription =>
+            subscription.Status == StripeConstants.SubscriptionStatus.Incomplete).ToList();
+
+        // Process unpaid subscriptions
+        if (unpaidSubscriptions != null && unpaidSubscriptions.Count > 0)
+        {
+            foreach (var subscription in unpaidSubscriptions)
+            {
+                await AttemptToPayOpenSubscriptionAsync(subscription);
+            }
+        }
+
+        // Process incomplete subscriptions - only if there's exactly one to avoid overcharging
+        if (incompleteSubscriptions == null || incompleteSubscriptions.Count == 0)
         {
             return;
         }
 
-        foreach (var unpaidSubscription in unpaidSubscriptions)
+        if (incompleteSubscriptions.Count > 1)
         {
-            await AttemptToPayOpenSubscriptionAsync(unpaidSubscription);
+            _logger.LogWarning(
+                "Customer {CustomerId} has {Count} incomplete subscriptions. Skipping automatic payment retry to avoid overcharging. Subscription IDs: {SubscriptionIds}",
+                customer.Id,
+                incompleteSubscriptions.Count,
+                string.Join(", ", incompleteSubscriptions.Select(s => s.Id)));
+            return;
         }
+
+        // Exactly one incomplete subscription - safe to retry
+        await AttemptToPayOpenSubscriptionAsync(incompleteSubscriptions.First());
     }
 
-    private async Task AttemptToPayOpenSubscriptionAsync(Subscription unpaidSubscription)
+    private async Task AttemptToPayOpenSubscriptionAsync(Subscription subscription)
     {
-        var latestInvoice = unpaidSubscription.LatestInvoice;
+        var latestInvoice = subscription.LatestInvoice;
 
-        if (unpaidSubscription.LatestInvoice is null)
+        if (subscription.LatestInvoice is null)
         {
             _logger.LogWarning(
-                "Attempted to pay unpaid subscription {SubscriptionId} but latest invoice didn't exist",
-                unpaidSubscription.Id);
+                "Attempted to pay subscription {SubscriptionId} with status {Status} but latest invoice didn't exist",
+                subscription.Id, subscription.Status);
 
             return;
         }
 
         if (latestInvoice.Status != StripeInvoiceStatus.Open)
         {
             _logger.LogWarning(
-                "Attempted to pay unpaid subscription {SubscriptionId} but latest invoice wasn't \"open\"",
-                unpaidSubscription.Id);
+                "Attempted to pay subscription {SubscriptionId} with status {Status} but latest invoice wasn't \"open\"",
+                subscription.Id, subscription.Status);
 
             return;
         }
@@ -144,8 +165,8 @@ private async Task AttemptToPayOpenSubscriptionAsync(Subscription unpaidSubscrip
         catch (Exception e)
         {
             _logger.LogError(e,
-                "Attempted to pay open invoice {InvoiceId} on unpaid subscription {SubscriptionId} but encountered an error",
-                latestInvoice.Id, unpaidSubscription.Id);
+                "Attempted to pay open invoice {InvoiceId} on subscription {SubscriptionId} with status {Status} but encountered an error",
+                latestInvoice.Id, subscription.Id, subscription.Status);
             throw;
         }
     }

src/Billing/Services/Implementations/SubscriptionUpdatedHandler.cs

@@ -69,7 +69,8 @@ public async Task HandleAsync(Event parsedEvent)
 
         var currentPeriodEnd = subscription.GetCurrentPeriodEnd();
 
-        if (SubscriptionWentUnpaid(parsedEvent, subscription))
+        if (SubscriptionWentUnpaid(parsedEvent, subscription) ||
+            SubscriptionWentIncompleteExpired(parsedEvent, subscription))
         {
             await DisableSubscriberAsync(subscriberId, currentPeriodEnd);
             await SetSubscriptionToCancelAsync(subscription);
@@ -111,6 +112,18 @@ SubscriptionStatus.Active or
             LatestInvoice.BillingReason: BillingReasons.SubscriptionCreate or BillingReasons.SubscriptionCycle
         };
 
+    private static bool SubscriptionWentIncompleteExpired(
+        Event parsedEvent,
+        Subscription currentSubscription) =>
+        parsedEvent.Data.PreviousAttributes.ToObject<Subscription>() is Subscription
+        {
+            Status: SubscriptionStatus.Incomplete
+        } && currentSubscription is
+        {
+            Status: SubscriptionStatus.IncompleteExpired,
+            LatestInvoice.BillingReason: BillingReasons.SubscriptionCreate or BillingReasons.SubscriptionCycle
+        };
+
     private static bool SubscriptionBecameActive(
         Event parsedEvent,
         Subscription currentSubscription) =>

src/Core/Billing/Payment/Commands/UpdatePaymentMethodCommand.cs

@@ -3,6 +3,7 @@
 using Bit.Core.Billing.Constants;
 using Bit.Core.Billing.Payment.Models;
 using Bit.Core.Billing.Services;
+using Bit.Core.Billing.Subscriptions.Models;
 using Bit.Core.Entities;
 using Bit.Core.Services;
 using Bit.Core.Settings;
@@ -143,6 +144,24 @@ private async Task<BillingCommandResult<MaskedPaymentMethod>> AddPayPalAsync(
             await stripeAdapter.UpdateCustomerAsync(customer.Id, new CustomerUpdateOptions { Metadata = metadata });
         }
 
+        // If the subscriber has an incomplete subscription, pay the invoice with the new PayPal payment method
+        if (!string.IsNullOrEmpty(subscriber.GatewaySubscriptionId))
+        {
+            var subscription = await stripeAdapter.GetSubscriptionAsync(subscriber.GatewaySubscriptionId);
+
+            if (subscription.Status == StripeConstants.SubscriptionStatus.Incomplete)
+            {
+                var invoice = await stripeAdapter.UpdateInvoiceAsync(subscription.LatestInvoiceId,
+                    new InvoiceUpdateOptions
+                    {
+                        AutoAdvance = false,
+                        Expand = ["customer"]
+                    });
+
+                await braintreeService.PayInvoice(new UserId(subscriber.Id), invoice);
+            }
+        }
+
         var payPalAccount = braintreeCustomer.DefaultPaymentMethod as PayPalAccount;
 
         return MaskedPaymentMethod.From(payPalAccount!);

src/Core/Billing/Premium/Commands/CreatePremiumCloudHostedSubscriptionCommand.cs

@@ -72,7 +72,13 @@ public Task<BillingCommandResult<None>> Run(
         BillingAddress billingAddress,
         short additionalStorageGb) => HandleAsync<None>(async () =>
     {
-        if (user.Premium)
+        // A "terminal" subscription is one that has ended and cannot be renewed/reactivated.
+        // These are: 'canceled' (user canceled) and 'incomplete_expired' (payment failed and time expired).
+        // We allow users with terminal subscriptions to create a new subscription even if user.Premium is still true,
+        // enabling the resubscribe workflow without requiring Premium status to be cleared first.
+        var hasTerminalSubscription = await HasTerminalSubscriptionAsync(user);
+
+        if (user.Premium && !hasTerminalSubscription)
         {
             return new BadRequest("Already a premium user.");
         }
@@ -98,8 +104,11 @@ public Task<BillingCommandResult<None>> Run(
          * purchased account credit but chose to use a tokenizable payment method to pay for the subscription. In this case,
          * we need to add the payment method to their customer first. If the incoming payment method is account credit,
          * we can just go straight to fetching the customer since there's no payment method to apply.
+         *
+         * Additionally, if this is a resubscribe scenario with a tokenized payment method, we should update the payment method
+         * to ensure the new payment method is used instead of the old one.
          */
-        else if (paymentMethod.IsTokenized && !await hasPaymentMethodQuery.Run(user))
+        else if (paymentMethod.IsTokenized && (!await hasPaymentMethodQuery.Run(user) || hasTerminalSubscription))
         {
             await updatePaymentMethodCommand.Run(user, paymentMethod.AsTokenized, billingAddress);
             customer = await subscriberService.GetCustomerOrThrow(user, new CustomerGetOptions { Expand = _expand });
@@ -122,7 +131,7 @@ public Task<BillingCommandResult<None>> Run(
                     case { Type: TokenizablePaymentMethodType.PayPal }
                         when subscription.Status == SubscriptionStatus.Incomplete:
                     case { Type: not TokenizablePaymentMethodType.PayPal }
-                        when subscription.Status == SubscriptionStatus.Active:
+                        when subscription.Status is SubscriptionStatus.Active or SubscriptionStatus.Incomplete:
                         {
                             user.Premium = true;
                             user.PremiumExpirationDate = subscription.GetCurrentPeriodEnd();
@@ -369,4 +378,28 @@ private async Task<Subscription> CreateSubscriptionAsync(
 
         return subscription;
     }
+
+    private async Task<bool> HasTerminalSubscriptionAsync(User user)
+    {
+        if (string.IsNullOrEmpty(user.GatewaySubscriptionId))
+        {
+            return false;
+        }
+
+        try
+        {
+            var existingSubscription = await stripeAdapter.GetSubscriptionAsync(user.GatewaySubscriptionId);
+            return existingSubscription.Status is
+                SubscriptionStatus.Canceled or
+                SubscriptionStatus.IncompleteExpired;
+        }
+        catch (Exception ex)
+        {
+            // Subscription doesn't exist in Stripe or can't be fetched (e.g., network issues, invalid ID)
+            // Log the issue but proceed with subscription creation to avoid blocking legitimate resubscribe attempts
+            _logger.LogWarning(ex, "Unable to fetch existing subscription {SubscriptionId} for user {UserId}. Proceeding with subscription creation",
+                user.GatewaySubscriptionId, user.Id);
+            return false;
+        }
+    }
 }

src/Core/Billing/Subscriptions/Queries/GetBitwardenSubscriptionQuery.cs

@@ -31,16 +31,21 @@ public interface IGetBitwardenSubscriptionQuery
     /// Currently only supports <see cref="User"/> subscribers. Future versions will support all
     /// <see cref="ISubscriber"/> types (User and Organization).
     /// </remarks>
-    Task<BitwardenSubscription> Run(User user);
+    Task<BitwardenSubscription?> Run(User user);
 }
 
 public class GetBitwardenSubscriptionQuery(
     ILogger<GetBitwardenSubscriptionQuery> logger,
     IPricingClient pricingClient,
     IStripeAdapter stripeAdapter) : IGetBitwardenSubscriptionQuery
 {
-    public async Task<BitwardenSubscription> Run(User user)
+    public async Task<BitwardenSubscription?> Run(User user)
     {
+        if (string.IsNullOrEmpty(user.GatewaySubscriptionId))
+        {
+            return null;
+        }
+
         var subscription = await stripeAdapter.GetSubscriptionAsync(user.GatewaySubscriptionId, new SubscriptionGetOptions
         {
             Expand =