Merge pull request #20328 from mozilla/PAY-3602

david1alvarez · web-flow · commit 5ab20fd1fcdd · 2026-04-08T09:33:19.000-07:00
feat(payments-next): Cancel free trial on upgrade
diff --git a/apps/payments/next/app/[locale]/[offeringId]/[interval]/upgrade/[cartId]/(startLayout)/start/en.ftl b/apps/payments/next/app/[locale]/[offeringId]/[interval]/upgrade/[cartId]/(startLayout)/start/en.ftl
@@ -4,3 +4,5 @@ upgrade-page-payment-information = Payment Information
 
 # $nextInvoiceDate (number) - The date of the next invoice
 upgrade-page-acknowledgment =  Your plan will change immediately, and you’ll be charged a prorated amount today for the rest of this billing cycle. Starting { $nextInvoiceDate } you’ll be charged the full amount.
+
+upgrade-page-acknowledgment-from-trial = By upgrading, your active free trial will end immediately and you will be charged for your new plan today.
diff --git a/apps/payments/next/app/[locale]/[offeringId]/[interval]/upgrade/[cartId]/(startLayout)/start/page.tsx b/apps/payments/next/app/[locale]/[offeringId]/[interval]/upgrade/[cartId]/(startLayout)/start/page.tsx
@@ -150,20 +150,26 @@ export default async function Upgrade({
           className="leading-5 text-sm"
           data-testid="sub-update-acknowledgment"
         >
-          {l10n.getString(
-            'upgrade-page-acknowledgment',
-            {
-              nextInvoiceDate: l10n.getLocalizedDate(
-                cart.upcomingInvoicePreview.nextInvoiceDate
-              ),
-            },
-            `Your plan will change immediately, and you’ll be charged a prorated
+          {cart.isUpgradeFromTrial
+            ? l10n.getString(
+                'upgrade-page-acknowledgment-from-trial',
+                {},
+                `By upgrading, your active free trial will end immediately and you will be charged for your new plan today.`
+              )
+            : l10n.getString(
+                'upgrade-page-acknowledgment',
+                {
+                  nextInvoiceDate: l10n.getLocalizedDate(
+                    cart.upcomingInvoicePreview.nextInvoiceDate
+                  ),
+                },
+                `Your plan will change immediately, and you’ll be charged a prorated
           amount today for the rest of this billing cycle. Starting
           ${l10n.getLocalizedDateString(
             cart.upcomingInvoicePreview.nextInvoiceDate
           )}
           you’ll be charged the full amount.`
-          )}
+              )}
         </p>
 
         <div
diff --git a/libs/payments/cart/src/lib/cart.service.spec.ts b/libs/payments/cart/src/lib/cart.service.spec.ts
@@ -2013,6 +2013,7 @@ describe('CartService', () => {
         },
         hasActiveSubscriptions: true,
         freeTrialEligibility: null,
+        isUpgradeFromTrial: false,
       });
 
       expect(cartManager.fetchCartById).toHaveBeenCalledWith(mockCart.id);
@@ -2029,6 +2030,123 @@ describe('CartService', () => {
       });
     });
 
+    it('returns cart with isUpgradeFromTrial true and uses previewUpcomingForUpgrade with trialEnd when subscription is trialing with payment method', async () => {
+      const mockCart = ResultCartFactory({
+        state: CartState.START,
+        stripeSubscriptionId: null,
+        eligibilityStatus: CartEligibilityStatus.UPGRADE,
+      });
+      const mockCustomer = StripeResponseFactory(StripeCustomerFactory());
+      const mockPrice = StripePriceFactory({ currency: mockCart.currency });
+      const mockInvoicePreviewForUpgrade = InvoicePreviewFactory();
+      const mockFromOfferingId = faker.string.uuid();
+      const mockFromPrice = StripePriceFactory({
+        recurring: StripePriceRecurringFactory({ interval: 'month' }),
+      });
+      const mockPricingForCurrency = PricingForCurrencyFactory({
+        price: mockFromPrice,
+      });
+      const mockTrialingSubscription = StripeSubscriptionFactory({
+        status: 'trialing',
+      });
+
+      jest.spyOn(cartManager, 'fetchCartById').mockResolvedValue(mockCart);
+      jest
+        .spyOn(productConfigurationManager, 'retrieveStripePrice')
+        .mockResolvedValue(mockPrice);
+      jest.spyOn(customerManager, 'retrieve').mockResolvedValue(mockCustomer);
+      jest
+        .spyOn(invoiceManager, 'previewUpcomingForUpgrade')
+        .mockResolvedValue(mockInvoicePreviewForUpgrade);
+      jest.spyOn(eligibilityService, 'checkEligibility').mockResolvedValue({
+        subscriptionEligibilityResult: EligibilityStatus.UPGRADE,
+        fromOfferingConfigId: mockFromOfferingId,
+        fromPrice: mockFromPrice,
+      });
+      jest
+        .spyOn(subscriptionManager, 'retrieveForCustomerAndPrice')
+        .mockResolvedValue(mockTrialingSubscription);
+      jest
+        .spyOn(priceManager, 'retrievePricingForCurrency')
+        .mockResolvedValue(mockPricingForCurrency);
+
+      const result = await cartService.getCart(mockCart.id);
+      expect(invoiceManager.previewUpcomingForUpgrade).toHaveBeenCalledWith(
+        expect.objectContaining({
+          trialEnd: expect.any(Number),
+        })
+      );
+      expect(result).toEqual(
+        expect.objectContaining({
+          isUpgradeFromTrial: true,
+        })
+      );
+    });
+
+    it('uses previewUpcoming for trialing upgrade with no payment method', async () => {
+      const mockCart = ResultCartFactory({
+        state: CartState.START,
+        stripeSubscriptionId: null,
+        eligibilityStatus: CartEligibilityStatus.UPGRADE,
+      });
+      const mockCustomerNoPaymentMethod = StripeResponseFactory(
+        StripeCustomerFactory({
+          invoice_settings: {
+            custom_fields: null,
+            default_payment_method: null,
+            footer: null,
+            rendering_options: null,
+          },
+        })
+      );
+      const mockPrice = StripePriceFactory({ currency: mockCart.currency });
+      const mockInvoicePreview = InvoicePreviewFactory();
+      const mockFromOfferingId = faker.string.uuid();
+      const mockFromPrice = StripePriceFactory({
+        recurring: StripePriceRecurringFactory({ interval: 'month' }),
+      });
+      const mockPricingForCurrency = PricingForCurrencyFactory({
+        price: mockFromPrice,
+      });
+      const mockTrialingSubscription = StripeSubscriptionFactory({
+        status: 'trialing',
+      });
+
+      jest.spyOn(cartManager, 'fetchCartById').mockResolvedValue(mockCart);
+      jest
+        .spyOn(productConfigurationManager, 'retrieveStripePrice')
+        .mockResolvedValue(mockPrice);
+      jest
+        .spyOn(customerManager, 'retrieve')
+        .mockResolvedValue(mockCustomerNoPaymentMethod);
+      const previewUpcomingSpy = jest
+        .spyOn(invoiceManager, 'previewUpcoming')
+        .mockResolvedValue(mockInvoicePreview);
+      const previewUpgradespy = jest
+        .spyOn(invoiceManager, 'previewUpcomingForUpgrade')
+        .mockResolvedValue(mockInvoicePreview);
+      jest.spyOn(eligibilityService, 'checkEligibility').mockResolvedValue({
+        subscriptionEligibilityResult: EligibilityStatus.UPGRADE,
+        fromOfferingConfigId: mockFromOfferingId,
+        fromPrice: mockFromPrice,
+      });
+      jest
+        .spyOn(subscriptionManager, 'retrieveForCustomerAndPrice')
+        .mockResolvedValue(mockTrialingSubscription);
+      jest
+        .spyOn(priceManager, 'retrievePricingForCurrency')
+        .mockResolvedValue(mockPricingForCurrency);
+
+      const result = await cartService.getCart(mockCart.id);
+      expect(previewUpcomingSpy).toHaveBeenCalled();
+      expect(previewUpgradespy).not.toHaveBeenCalled();
+      expect(result).toEqual(
+        expect.objectContaining({
+          isUpgradeFromTrial: true,
+        })
+      );
+    });
+
     it('throws error if offeringPrice could not be retrieved', async () => {
       const mockCart = ResultCartFactory({
         state: CartState.START,
diff --git a/libs/payments/cart/src/lib/cart.service.ts b/libs/payments/cart/src/lib/cart.service.ts
@@ -925,6 +925,7 @@ export class CartService {
     }
 
     let upcomingInvoicePreview: InvoicePreview | undefined;
+    let isUpgradeFromTrial: boolean | undefined;
     if (
       cartEligibilityStatus === CartEligibilityStatus.UPGRADE &&
       cart.state !== CartState.FAIL
@@ -940,13 +941,29 @@ export class CartService {
           eligibility.fromPrice.id
         );
       assert(fromSubscription, new GetCartSubscriptionMissingError(cartId));
+      isUpgradeFromTrial = fromSubscription.status === 'trialing';
       const fromSubscriptionItem = retrieveSubscriptionItem(fromSubscription);
-      upcomingInvoicePreview =
-        await this.invoiceManager.previewUpcomingForUpgrade({
+      const hasPaymentMethod =
+        !!customer.invoice_settings.default_payment_method;
+      if (isUpgradeFromTrial && !hasPaymentMethod) {
+        upcomingInvoicePreview = await this.invoiceManager.previewUpcoming({
           priceId: price.id,
+          currency: cart.currency,
           customer,
-          fromSubscriptionItem,
+          taxAddress: cart.taxAddress,
+          couponCode: cart.couponCode || undefined,
         });
+      } else {
+        upcomingInvoicePreview =
+          await this.invoiceManager.previewUpcomingForUpgrade({
+            priceId: price.id,
+            customer,
+            fromSubscriptionItem,
+            ...(isUpgradeFromTrial && {
+              trialEnd: Math.floor(Date.now() / 1000),
+            }),
+          });
+      }
     } else {
       upcomingInvoicePreview = await this.invoiceManager.previewUpcoming({
         priceId: price.id,
@@ -1032,6 +1049,7 @@ export class CartService {
         freeTrialEligibility,
         trialStartDate,
         trialEndDate,
+        isUpgradeFromTrial,
       };
     }
 
@@ -1086,6 +1104,7 @@ export class CartService {
       freeTrialEligibility,
       trialStartDate,
       trialEndDate,
+      isUpgradeFromTrial,
     };
   }
 
diff --git a/libs/payments/cart/src/lib/cart.types.ts b/libs/payments/cart/src/lib/cart.types.ts
@@ -83,6 +83,7 @@ export type BaseCartDTO = Omit<ResultCart, 'state'> & {
   freeTrialEligibility?: FreeTrial | null;
   trialStartDate?: number;
   trialEndDate?: number;
+  isUpgradeFromTrial?: boolean;
 };
 
 export type StartCartDTO = BaseCartDTO & {
diff --git a/libs/payments/cart/src/lib/checkout.service.spec.ts b/libs/payments/cart/src/lib/checkout.service.spec.ts
@@ -2315,6 +2315,60 @@ describe('CheckoutService', () => {
         )
       ).rejects.toThrow(/UpgradeSubscriptionNullCurrencyError/);
     });
+
+    it('passes trial_end now and trial_settings create_invoice when subscription is trialing', async () => {
+      const trialingSubscription = StripeSubscriptionFactory({
+        status: 'trialing',
+      });
+      jest
+        .spyOn(subscriptionManager, 'retrieveForCustomerAndPrice')
+        .mockReset()
+        .mockResolvedValueOnce(trialingSubscription);
+      jest
+        .spyOn(subscriptionManager, 'update')
+        .mockReset()
+        .mockResolvedValueOnce(
+          StripeResponseFactory(trialingSubscription)
+        );
+
+      await checkoutService.upgradeSubscription(
+        customerId,
+        toPriceId,
+        fromPriceId,
+        cart,
+        [],
+        mockAttributionData
+      );
+      expect(subscriptionManager.update).toHaveBeenCalledWith(
+        trialingSubscription.id,
+        expect.objectContaining({
+          trial_end: 'now',
+          trial_settings: {
+            end_behavior: {
+              missing_payment_method: 'create_invoice',
+            },
+          },
+        })
+      );
+    });
+
+    it('does not pass trial_end or trial_settings when subscription is active', async () => {
+      await checkoutService.upgradeSubscription(
+        customerId,
+        toPriceId,
+        fromPriceId,
+        cart,
+        [],
+        mockAttributionData
+      );
+      expect(subscriptionManager.update).toHaveBeenCalledWith(
+        subscription.id,
+        expect.not.objectContaining({
+          trial_end: expect.anything(),
+          trial_settings: expect.anything(),
+        })
+      );
+    });
   });
 
   describe('determineCheckoutAmount', () => {
@@ -2367,6 +2421,58 @@ describe('CheckoutService', () => {
       expect(result).toEqual(mockInvoicePreviewForUpgrade.subtotal);
     });
 
+    it('uses previewUpcoming for trialing upgrade with no payment method', async () => {
+      const trialingSubscription = StripeSubscriptionFactory({
+        status: 'trialing',
+      });
+      const customerNoPaymentMethod = StripeCustomerFactory({
+        invoice_settings: {
+          custom_fields: null,
+          default_payment_method: null,
+          footer: null,
+          rendering_options: null,
+        },
+      });
+      jest
+        .spyOn(subscriptionManager, 'retrieveForCustomerAndPrice')
+        .mockResolvedValue(trialingSubscription);
+
+      const result = await checkoutService.determineCheckoutAmount({
+        eligibility: mockEligibilityUpgrade,
+        customer: customerNoPaymentMethod,
+        priceId: mockPrice.id,
+        currency: mockCurrency,
+        taxAddress: mockTaxAddress,
+      });
+      expect(invoiceManager.previewUpcoming).toHaveBeenCalled();
+      expect(invoiceManager.previewUpcomingForUpgrade).not.toHaveBeenCalled();
+      expect(result).toEqual(mockInvoicePreview.subtotal);
+    });
+
+    it('uses previewUpcomingForUpgrade with trialEnd for trialing upgrade with payment method', async () => {
+      const trialingSubscription = StripeSubscriptionFactory({
+        status: 'trialing',
+      });
+      jest
+        .spyOn(subscriptionManager, 'retrieveForCustomerAndPrice')
+        .mockResolvedValue(trialingSubscription);
+
+      const result = await checkoutService.determineCheckoutAmount({
+        eligibility: mockEligibilityUpgrade,
+        customer: mockCustomer,
+        priceId: mockPrice.id,
+        currency: mockCurrency,
+        taxAddress: mockTaxAddress,
+      });
+      expect(invoiceManager.previewUpcomingForUpgrade).toHaveBeenCalledWith(
+        expect.objectContaining({
+          trialEnd: expect.any(Number),
+        })
+      );
+      expect(invoiceManager.previewUpcoming).not.toHaveBeenCalled();
+      expect(result).toEqual(mockInvoicePreviewForUpgrade.subtotal);
+    });
+
     it('rejects with customer assertion failure', async () => {
       // An issue with node assert.ok() and jest prevents testing that the
       // correct error is thrown.
diff --git a/libs/payments/cart/src/lib/checkout.service.ts b/libs/payments/cart/src/lib/checkout.service.ts
diff --git a/libs/payments/customer/src/lib/invoice.manager.ts b/libs/payments/customer/src/lib/invoice.manager.ts
