fix(billing): redirect to Stripe payment method setup when subscribing without payment method (#16827)

## Summary

When users click 'Subscribe Now' during a trial period without a payment
method configured, they previously saw an unhelpful error message: "No
payment method found. Please update your billing details."

This PR improves the UX by redirecting users directly to Stripe's
billing portal payment method update flow, where they can add their
payment information. After adding a payment method, users are redirected
back to the billing settings page and can click 'Subscribe Now' again to
successfully activate their subscription.

## Changes

### Backend
- **stripe-billing-portal.service.ts**: Added
`createBillingPortalSessionForPaymentMethodUpdate` method that creates a
Stripe billing portal session with `flow_data.type:
'payment_method_update'`
- **billing-portal.workspace-service.ts**: Added
`computeBillingPortalSessionURLForPaymentMethodUpdate` method to build
the portal URL
- **billing-end-trial-period.output.ts**: Added optional
`billingPortalUrl` field to the GraphQL output DTO
- **billing-subscription.service.ts**: Modified `endTrialPeriod` to
return `stripeCustomerId` when no payment method exists
- **billing.resolver.ts**: Updated resolver to orchestrate billing
portal URL generation when no payment method

### Frontend
- **useEndSubscriptionTrialPeriod.ts**: Redirect to billing portal URL
instead of showing error snackbar
- **endSubscriptionTrialPeriod.ts**: Added `billingPortalUrl` to
mutation response fields

## User Flow

1. User clicks "Subscribe Now" during trial
2. Backend checks for payment method
3. If no payment method → redirect to Stripe billing portal payment
method update page
4. User adds payment method in Stripe
5. User is redirected back to `/settings/billing`
6. User clicks "Subscribe Now" again to activate subscription

packages/twenty-front/src/generated-metadata/graphql.ts

@@ -388,6 +388,8 @@ export type Billing = {
 
 export type BillingEndTrialPeriodOutput = {
   __typename?: 'BillingEndTrialPeriodOutput';
+  /** Billing portal URL for payment method update (returned when no payment method exists) */
+  billingPortalUrl?: Maybe<Scalars['String']>;
   /** Boolean that confirms if a payment method was found */
   hasPaymentMethod: Scalars['Boolean'];
   /** Updated subscription status */
@@ -5440,7 +5442,7 @@ export type CheckoutSessionMutation = { __typename?: 'Mutation', checkoutSession
 export type EndSubscriptionTrialPeriodMutationVariables = Exact<{ [key: string]: never; }>;
 
 
-export type EndSubscriptionTrialPeriodMutation = { __typename?: 'Mutation', endSubscriptionTrialPeriod: { __typename?: 'BillingEndTrialPeriodOutput', status?: SubscriptionStatus | null, hasPaymentMethod: boolean } };
+export type EndSubscriptionTrialPeriodMutation = { __typename?: 'Mutation', endSubscriptionTrialPeriod: { __typename?: 'BillingEndTrialPeriodOutput', status?: SubscriptionStatus | null, hasPaymentMethod: boolean, billingPortalUrl?: string | null } };
 
 export type SetMeteredSubscriptionPriceMutationVariables = Exact<{
   priceId: Scalars['String'];
@@ -9129,6 +9131,7 @@ export const EndSubscriptionTrialPeriodDocument = gql`
   endSubscriptionTrialPeriod {
     status
     hasPaymentMethod
+    billingPortalUrl
   }
 }
     `;

packages/twenty-front/src/generated/graphql.ts

@@ -388,6 +388,8 @@ export type Billing = {
 
 export type BillingEndTrialPeriodOutput = {
   __typename?: 'BillingEndTrialPeriodOutput';
+  /** Billing portal URL for payment method update (returned when no payment method exists) */
+  billingPortalUrl?: Maybe<Scalars['String']>;
   /** Boolean that confirms if a payment method was found */
   hasPaymentMethod: Scalars['Boolean'];
   /** Updated subscription status */

packages/twenty-front/src/modules/billing/graphql/mutations/endSubscriptionTrialPeriod.ts

@@ -5,6 +5,7 @@ export const END_SUBSCRIPTION_TRIAL_PERIOD = gql`
     endSubscriptionTrialPeriod {
       status
       hasPaymentMethod
+      billingPortalUrl
     }
   }
 `;

packages/twenty-front/src/modules/billing/hooks/useEndSubscriptionTrialPeriod.ts

@@ -1,4 +1,5 @@
 import { currentWorkspaceState } from '@/auth/states/currentWorkspaceState';
+import { useRedirect } from '@/domain-manager/hooks/useRedirect';
 import { useSnackBar } from '@/ui/feedback/snack-bar-manager/hooks/useSnackBar';
 import { t } from '@lingui/core/macro';
 import { useState } from 'react';
@@ -13,6 +14,7 @@ export const useEndSubscriptionTrialPeriod = () => {
     currentWorkspaceState,
   );
   const [isLoading, setIsLoading] = useState(false);
+  const { redirect } = useRedirect();
 
   const endTrialPeriod = async () => {
     try {
@@ -24,6 +26,14 @@ export const useEndSubscriptionTrialPeriod = () => {
       const hasPaymentMethod = endTrialPeriodOutput?.hasPaymentMethod;
 
       if (isDefined(hasPaymentMethod) && hasPaymentMethod === false) {
+        const billingPortalUrl = endTrialPeriodOutput?.billingPortalUrl;
+
+        if (isDefined(billingPortalUrl)) {
+          redirect(billingPortalUrl);
+
+          return { success: false };
+        }
+
         enqueueErrorSnackBar({
           message: t`No payment method found. Please update your billing details.`,
         });

packages/twenty-server/src/engine/core-modules/billing/billing.resolver.ts

@@ -266,7 +266,28 @@ export class BillingResolver {
   async endSubscriptionTrialPeriod(
     @AuthWorkspace() workspace: WorkspaceEntity,
   ): Promise<BillingEndTrialPeriodOutput> {
-    return await this.billingSubscriptionService.endTrialPeriod(workspace);
+    const result =
+      await this.billingSubscriptionService.endTrialPeriod(workspace);
+
+    if (!result.hasPaymentMethod && result.stripeCustomerId) {
+      const billingPortalUrl =
+        await this.billingPortalWorkspaceService.computeBillingPortalSessionURLForPaymentMethodUpdate(
+          workspace,
+          result.stripeCustomerId,
+          '/settings/billing',
+        );
+
+      return {
+        hasPaymentMethod: false,
+        status: undefined,
+        billingPortalUrl,
+      };
+    }
+
+    return {
+      hasPaymentMethod: result.hasPaymentMethod,
+      status: result.status,
+    };
   }
 
   @Query(() => [BillingMeteredProductUsageOutput])

packages/twenty-server/src/engine/core-modules/billing/dtos/outputs/billing-end-trial-period.output.ts

@@ -16,4 +16,11 @@ export class BillingEndTrialPeriodOutput {
     description: 'Boolean that confirms if a payment method was found',
   })
   hasPaymentMethod: boolean;
+
+  @Field(() => String, {
+    description:
+      'Billing portal URL for payment method update (returned when no payment method exists)',
+    nullable: true,
+  })
+  billingPortalUrl?: string;
 }

packages/twenty-server/src/engine/core-modules/billing/services/billing-portal.workspace-service.ts

@@ -3,7 +3,12 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 
-import { findOrThrow, isDefined, isNonEmptyArray } from 'twenty-shared/utils';
+import {
+  assertIsDefinedOrThrow,
+  findOrThrow,
+  isDefined,
+  isNonEmptyArray,
+} from 'twenty-shared/utils';
 import { Not, Repository } from 'typeorm';
 
 import type Stripe from 'stripe';
@@ -26,7 +31,6 @@ import { type BillingPortalCheckoutSessionParameters } from 'src/engine/core-mod
 import { WorkspaceDomainsService } from 'src/engine/core-modules/domain/workspace-domains/services/workspace-domains.service';
 import { UserWorkspaceEntity } from 'src/engine/core-modules/user-workspace/user-workspace.entity';
 import { type WorkspaceEntity } from 'src/engine/core-modules/workspace/workspace.entity';
-import { assert } from 'src/utils/assert';
 
 @Injectable()
 export class BillingPortalWorkspaceService {
@@ -73,7 +77,13 @@ export class BillingPortalWorkspaceService {
           !isDefined(customer) || customer.billingSubscriptions.length === 0,
       });
 
-    assert(checkoutSession.url, 'Error: missing checkout.session.url');
+    assertIsDefinedOrThrow(
+      checkoutSession.url,
+      new BillingException(
+        'Error: missing checkout.session.url',
+        BillingExceptionCode.BILLING_STRIPE_ERROR,
+      ),
+    );
 
     return checkoutSession.url;
   }
@@ -209,7 +219,44 @@ export class BillingPortalWorkspaceService {
         returnUrl,
       );
 
-    assert(session.url, 'Error: missing billingPortal.session.url');
+    assertIsDefinedOrThrow(
+      session.url,
+      new BillingException(
+        'Error: missing billingPortal.session.url',
+        BillingExceptionCode.BILLING_STRIPE_ERROR,
+      ),
+    );
+
+    return session.url;
+  }
+
+  async computeBillingPortalSessionURLForPaymentMethodUpdate(
+    workspace: WorkspaceEntity,
+    stripeCustomerId: string,
+    returnUrlPath?: string,
+  ) {
+    const frontBaseUrl = this.workspaceDomainsService.buildWorkspaceURL({
+      workspace,
+    });
+
+    if (returnUrlPath) {
+      frontBaseUrl.pathname = returnUrlPath;
+    }
+    const returnUrl = frontBaseUrl.toString();
+
+    const session =
+      await this.stripeBillingPortalService.createBillingPortalSessionForPaymentMethodUpdate(
+        stripeCustomerId,
+        returnUrl,
+      );
+
+    assertIsDefinedOrThrow(
+      session.url,
+      new BillingException(
+        'Error: missing billingPortal.session.url',
+        BillingExceptionCode.BILLING_STRIPE_ERROR,
+      ),
+    );
 
     return session.url;
   }

packages/twenty-server/src/engine/core-modules/billing/services/billing-subscription.service.ts

@@ -205,7 +205,11 @@ export class BillingSubscriptionService {
     );
 
     if (!hasPaymentMethod) {
-      return { hasPaymentMethod: false, status: undefined };
+      return {
+        hasPaymentMethod: false,
+        status: undefined,
+        stripeCustomerId: billingSubscription.stripeCustomerId,
+      };
     }
 
     const updatedSubscription =

packages/twenty-server/src/engine/core-modules/billing/stripe/services/stripe-billing-portal.service.ts

@@ -36,4 +36,18 @@ export class StripeBillingPortalService {
         returnUrl ?? this.domainServerConfigService.getBaseUrl().toString(),
     });
   }
+
+  async createBillingPortalSessionForPaymentMethodUpdate(
+    stripeCustomerId: string,
+    returnUrl?: string,
+  ): Promise<Stripe.BillingPortal.Session> {
+    return await this.stripe.billingPortal.sessions.create({
+      customer: stripeCustomerId,
+      return_url:
+        returnUrl ?? this.domainServerConfigService.getBaseUrl().toString(),
+      flow_data: {
+        type: 'payment_method_update',
+      },
+    });
+  }
 }