From 76822982f3f10390a944d2d386ce6a2a236d8610 Mon Sep 17 00:00:00 2001
From: jnsdls <jonas.daniels@outlook.com>
Date: Mon, 14 Apr 2025 14:19:42 +0000
Subject: [PATCH] Add billing warning and open invoice filtering (#6718)

# Add Warning for Teams with Invalid Payment Methods

This PR adds a warning message for teams with invalid payment methods, preventing them from upgrading plans until they resolve outstanding invoices.

## Changes:

- Added a warning component that displays when a team has an `invalidPayment` billing status
- Added a filter to view only open invoices in the invoices page
- Updated the `getTeamInvoices` function to accept an optional `status` parameter
- Disabled checkout buttons for teams with invalid payment methods
- Added a warning in the cancel plan modal for teams with unpaid invoices
- Added a link to direct users to pay their outstanding invoices

These changes help users understand why they can't upgrade their plan and guides them to resolve payment issues.
---
 .../dashboard/src/@/actions/stripe-actions.ts |  4 +-
 apps/dashboard/src/@/components/billing.tsx   | 87 +++++++++++++------
 .../src/@/components/blocks/pricing-card.tsx  |  3 +
 .../team-onboarding/InviteTeamMembers.tsx     |  6 ++
 .../billing/components/PlanInfoCard.tsx       |  2 +
 .../invoices/components/billing-filter.tsx    | 46 ++++++++++
 .../invoices/components/billing-history.tsx   |  9 ++
 .../(team)/~/settings/invoices/page.tsx       | 26 ++++--
 .../~/settings/invoices/search-params.ts      |  3 +-
 .../CancelPlanModal/CancelPlanModal.tsx       | 28 +++++-
 .../settings/Account/Billing/Pricing.tsx      |  4 +
 11 files changed, 181 insertions(+), 37 deletions(-)
 create mode 100644 apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/components/billing-filter.tsx

diff --git a/apps/dashboard/src/@/actions/stripe-actions.ts b/apps/dashboard/src/@/actions/stripe-actions.ts
index ed88ae191b5..8009cbc2386 100644
--- a/apps/dashboard/src/@/actions/stripe-actions.ts
+++ b/apps/dashboard/src/@/actions/stripe-actions.ts
@@ -23,7 +23,7 @@ function getStripe() {
 
 export async function getTeamInvoices(
   team: Team,
-  options?: { cursor?: string },
+  options?: { cursor?: string; status?: "open" },
 ) {
   try {
     const customerId = team.stripeCustomerId;
@@ -37,6 +37,8 @@ export async function getTeamInvoices(
       customer: customerId,
       limit: 10,
       starting_after: options?.cursor,
+      // Only return open invoices if the status is open
+      status: options?.status,
     });
 
     return invoices;
diff --git a/apps/dashboard/src/@/components/billing.tsx b/apps/dashboard/src/@/components/billing.tsx
index 8aa011b7d2a..d0137111d78 100644
--- a/apps/dashboard/src/@/components/billing.tsx
+++ b/apps/dashboard/src/@/components/billing.tsx
@@ -1,6 +1,8 @@
 "use client";
 
 import { useMutation } from "@tanstack/react-query";
+import { AlertTriangleIcon } from "lucide-react";
+import Link from "next/link";
 import { toast } from "sonner";
 import type {
   GetBillingCheckoutUrlAction,
@@ -8,6 +10,7 @@ import type {
   GetBillingPortalUrlAction,
   GetBillingPortalUrlOptions,
 } from "../actions/billing";
+import type { Team } from "../api/team";
 import { cn } from "../lib/utils";
 import { Spinner } from "./ui/Spinner/Spinner";
 import { Button, type ButtonProps } from "./ui/button";
@@ -16,6 +19,7 @@ type CheckoutButtonProps = Omit<GetBillingCheckoutUrlOptions, "redirectUrl"> & {
   getBillingCheckoutUrl: GetBillingCheckoutUrlAction;
   buttonProps?: Omit<ButtonProps, "children">;
   children: React.ReactNode;
+  billingStatus: Team["billingStatus"];
 };
 
 export function CheckoutButton({
@@ -25,6 +29,7 @@ export function CheckoutButton({
   getBillingCheckoutUrl,
   children,
   buttonProps,
+  billingStatus,
 }: CheckoutButtonProps) {
   const getUrlMutation = useMutation({
     mutationFn: async () => {
@@ -40,35 +45,65 @@ export function CheckoutButton({
   const errorMessage = "Failed to open checkout page";
 
   return (
-    <Button
-      {...buttonProps}
-      className={cn(buttonProps?.className, "gap-2")}
-      disabled={getUrlMutation.isPending || buttonProps?.disabled}
-      onClick={async (e) => {
-        buttonProps?.onClick?.(e);
-        getUrlMutation.mutate(undefined, {
-          onSuccess: (res) => {
-            if (!res.url) {
-              toast.error(errorMessage);
-              return;
-            }
+    <div className="flex w-full flex-col items-center gap-2">
+      {/* show warning if the team has an invalid payment method */}
+      {billingStatus === "invalidPayment" && (
+        <BillingWarning teamSlug={teamSlug} />
+      )}
+      <Button
+        {...buttonProps}
+        className={cn(buttonProps?.className, "w-full gap-2")}
+        disabled={
+          // disable button if the team has an invalid payment method
+          // api will return 402 error if the team has an invalid payment method
+          billingStatus === "invalidPayment" ||
+          getUrlMutation.isPending ||
+          buttonProps?.disabled
+        }
+        onClick={async (e) => {
+          buttonProps?.onClick?.(e);
+          getUrlMutation.mutate(undefined, {
+            onSuccess: (res) => {
+              if (!res.url) {
+                toast.error(errorMessage);
+                return;
+              }
 
-            const tab = window.open(res.url, "_blank");
+              const tab = window.open(res.url, "_blank");
 
-            if (!tab) {
+              if (!tab) {
+                toast.error(errorMessage);
+                return;
+              }
+            },
+            onError: () => {
               toast.error(errorMessage);
-              return;
-            }
-          },
-          onError: () => {
-            toast.error(errorMessage);
-          },
-        });
-      }}
-    >
-      {getUrlMutation.isPending && <Spinner className="size-4" />}
-      {children}
-    </Button>
+            },
+          });
+        }}
+      >
+        {getUrlMutation.isPending && <Spinner className="size-4" />}
+        {children}
+      </Button>
+    </div>
+  );
+}
+
+function BillingWarning({ teamSlug }: { teamSlug: string }) {
+  return (
+    <div className="flex items-center gap-2 rounded-md border border-amber-200 bg-amber-50 p-3 text-amber-800 dark:border-amber-700/50 dark:bg-amber-900/30 dark:text-amber-400">
+      <AlertTriangleIcon className="h-5 w-5 flex-shrink-0" />
+      <p className="text-sm">
+        You have outstanding invoices. Please{" "}
+        <Link
+          href={`/team/${teamSlug}/~/settings/invoices?status=open`}
+          className="font-medium text-amber-700 underline transition-colors hover:text-amber-900 dark:text-amber-400 dark:hover:text-amber-300"
+        >
+          pay them
+        </Link>{" "}
+        to continue.
+      </p>
+    </div>
   );
 }
 
diff --git a/apps/dashboard/src/@/components/blocks/pricing-card.tsx b/apps/dashboard/src/@/components/blocks/pricing-card.tsx
index b517441ea2a..0ef29a9949f 100644
--- a/apps/dashboard/src/@/components/blocks/pricing-card.tsx
+++ b/apps/dashboard/src/@/components/blocks/pricing-card.tsx
@@ -30,6 +30,7 @@ type PricingCardCta = {
 
 type PricingCardProps = {
   teamSlug: string;
+  billingStatus: Team["billingStatus"];
   billingPlan: keyof typeof TEAM_PLANS;
   cta?: PricingCardCta;
   ctaHint?: string;
@@ -41,6 +42,7 @@ type PricingCardProps = {
 
 export const PricingCard: React.FC<PricingCardProps> = ({
   teamSlug,
+  billingStatus,
   billingPlan,
   cta,
   highlighted = false,
@@ -131,6 +133,7 @@ export const PricingCard: React.FC<PricingCardProps> = ({
         <div className="flex flex-col gap-3">
           {billingPlanToSkuMap[billingPlan] && cta.type === "checkout" && (
             <CheckoutButton
+              billingStatus={billingStatus}
               buttonProps={{
                 variant: highlighted ? "default" : "outline",
                 className: highlighted ? undefined : "bg-background",
diff --git a/apps/dashboard/src/app/login/onboarding/team-onboarding/InviteTeamMembers.tsx b/apps/dashboard/src/app/login/onboarding/team-onboarding/InviteTeamMembers.tsx
index 374cd91ae17..c29f407fd56 100644
--- a/apps/dashboard/src/app/login/onboarding/team-onboarding/InviteTeamMembers.tsx
+++ b/apps/dashboard/src/app/login/onboarding/team-onboarding/InviteTeamMembers.tsx
@@ -77,6 +77,7 @@ export function InviteTeamMembersUI(props: {
       <Sheet open={showPlanModal} onOpenChange={setShowPlanModal}>
         <SheetContent className="!max-w-[1300px] w-full overflow-auto">
           <InviteModalContent
+            billingStatus={props.team.billingStatus}
             teamSlug={props.team.slug}
             getBillingCheckoutUrl={props.getBillingCheckoutUrl}
             trackEvent={props.trackEvent}
@@ -144,6 +145,7 @@ export function InviteTeamMembersUI(props: {
 
 function InviteModalContent(props: {
   teamSlug: string;
+  billingStatus: Team["billingStatus"];
   getBillingCheckoutUrl: GetBillingCheckoutUrlAction;
   trackEvent: (params: TrackingParams) => void;
 }) {
@@ -154,6 +156,7 @@ function InviteModalContent(props: {
   const starterPlan = (
     <PricingCard
       billingPlan="starter"
+      billingStatus={props.billingStatus}
       teamSlug={props.teamSlug}
       cta={{
         title: "Get Started",
@@ -174,6 +177,7 @@ function InviteModalContent(props: {
   const growthPlan = (
     <PricingCard
       billingPlan="growth"
+      billingStatus={props.billingStatus}
       teamSlug={props.teamSlug}
       cta={{
         title: "Get Started",
@@ -195,6 +199,7 @@ function InviteModalContent(props: {
   const acceleratePlan = (
     <PricingCard
       billingPlan="accelerate"
+      billingStatus={props.billingStatus}
       teamSlug={props.teamSlug}
       cta={{
         title: "Get started",
@@ -215,6 +220,7 @@ function InviteModalContent(props: {
   const scalePlan = (
     <PricingCard
       billingPlan="scale"
+      billingStatus={props.billingStatus}
       teamSlug={props.teamSlug}
       cta={{
         title: "Get started",
diff --git a/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/billing/components/PlanInfoCard.tsx b/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/billing/components/PlanInfoCard.tsx
index 42650c4b9b6..18ff84585e6 100644
--- a/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/billing/components/PlanInfoCard.tsx
+++ b/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/billing/components/PlanInfoCard.tsx
@@ -119,6 +119,8 @@ export function PlanInfoCardUI(props: {
             </Button>
 
             <CancelPlanButton
+              teamSlug={props.team.slug}
+              billingStatus={props.team.billingStatus}
               cancelPlan={props.cancelPlan}
               currentPlan={props.team.billingPlan}
               getTeam={props.getTeam}
diff --git a/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/components/billing-filter.tsx b/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/components/billing-filter.tsx
new file mode 100644
index 00000000000..eb9f7c71db2
--- /dev/null
+++ b/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/components/billing-filter.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { useQueryStates } from "nuqs";
+import { startTransition } from "react";
+import { searchParams } from "../search-params";
+
+export function BillingFilter() {
+  const [{ status }, setStates] = useQueryStates(
+    {
+      cursor: searchParams.cursor,
+      status: searchParams.status,
+    },
+    {
+      history: "push",
+      shallow: false,
+      startTransition,
+    },
+  );
+  return (
+    <Select
+      value={status ?? "all"}
+      onValueChange={(v) => {
+        setStates({
+          cursor: null,
+          // only set the status if it's "open", otherwise clear it
+          status: v === "open" ? "open" : null,
+        });
+      }}
+    >
+      <SelectTrigger className="w-48">
+        <SelectValue placeholder="Filter by status" />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem value="all">All Invoices</SelectItem>
+        <SelectItem value="open">Open Invoices</SelectItem>
+      </SelectContent>
+    </Select>
+  );
+}
diff --git a/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/components/billing-history.tsx b/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/components/billing-history.tsx
index ecade336024..d282f84d01e 100644
--- a/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/components/billing-history.tsx
+++ b/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/components/billing-history.tsx
@@ -25,6 +25,7 @@ import { searchParams } from "../search-params";
 
 export function BillingHistory(props: {
   invoices: Stripe.Invoice[];
+  status: "all" | "past_due" | "open";
   hasMore: boolean;
 }) {
   const [isLoading, startTransition] = useTransition();
@@ -74,6 +75,14 @@ export function BillingHistory(props: {
   };
 
   if (props.invoices.length === 0) {
+    if (props.status === "open") {
+      return (
+        <div className="py-6 text-center">
+          <Receipt className="mx-auto h-12 w-12 text-muted-foreground" />
+          <h3 className="mt-2 font-medium text-lg">No open invoices</h3>
+        </div>
+      );
+    }
     return (
       <div className="py-6 text-center">
         <Receipt className="mx-auto h-12 w-12 text-muted-foreground" />
diff --git a/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/page.tsx b/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/page.tsx
index 9e7621817b7..2d11eb68344 100644
--- a/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/page.tsx
+++ b/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/page.tsx
@@ -3,6 +3,7 @@ import { getTeamBySlug } from "@/api/team";
 import { redirect } from "next/navigation";
 import type { SearchParams } from "nuqs/server";
 import { getValidAccount } from "../../../../../../account/settings/getAccount";
+import { BillingFilter } from "./components/billing-filter";
 import { BillingHistory } from "./components/billing-history";
 import { searchParamLoader } from "./search-params";
 
@@ -31,19 +32,28 @@ export default async function Page(props: {
 
   const invoices = await getTeamInvoices(team, {
     cursor: searchParams.cursor ?? undefined,
+    status: searchParams.status ?? undefined,
   });
 
   return (
     <div className="overflow-hidden rounded-lg border bg-card">
-      <div className="p-6">
-        <h2 className="font-semibold text-2xl leading-none tracking-tight">
-          Invoice History
-        </h2>
-        <p className="mt-1 text-muted-foreground text-sm">
-          View your past invoices and payment history
-        </p>
+      <div className="flex items-center justify-between p-6">
+        <div className="flex flex-col gap-1">
+          <h2 className="font-semibold text-2xl leading-none tracking-tight">
+            Invoice History
+          </h2>
+          <p className="text-muted-foreground text-sm">
+            View your past invoices and payment history
+          </p>
+        </div>
+        <BillingFilter />
       </div>
-      <BillingHistory invoices={invoices.data} hasMore={invoices.has_more} />
+      <BillingHistory
+        invoices={invoices.data}
+        hasMore={invoices.has_more}
+        // fall back to "all" if the status is not set
+        status={searchParams.status ?? "all"}
+      />
     </div>
   );
 }
diff --git a/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/search-params.ts b/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/search-params.ts
index c43f7b8cb26..bdaca3e8f34 100644
--- a/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/search-params.ts
+++ b/apps/dashboard/src/app/team/[team_slug]/(team)/~/settings/invoices/search-params.ts
@@ -1,7 +1,8 @@
-import { createLoader, parseAsString } from "nuqs/server";
+import { createLoader, parseAsString, parseAsStringEnum } from "nuqs/server";
 
 export const searchParams = {
   cursor: parseAsString,
+  status: parseAsStringEnum(["open"]),
 };
 
 export const searchParamLoader = createLoader(searchParams);
diff --git a/apps/dashboard/src/components/settings/Account/Billing/CancelPlanModal/CancelPlanModal.tsx b/apps/dashboard/src/components/settings/Account/Billing/CancelPlanModal/CancelPlanModal.tsx
index 104a49e9a76..dbf288de489 100644
--- a/apps/dashboard/src/components/settings/Account/Billing/CancelPlanModal/CancelPlanModal.tsx
+++ b/apps/dashboard/src/components/settings/Account/Billing/CancelPlanModal/CancelPlanModal.tsx
@@ -83,8 +83,10 @@ const cancelReasons: Array<{
 ];
 
 export function CancelPlanButton(props: {
+  teamSlug: string;
   cancelPlan: CancelPlan;
   currentPlan: Team["billingPlan"];
+  billingStatus: Team["billingStatus"];
   getTeam: () => Promise<Team>;
 }) {
   return (
@@ -102,7 +104,9 @@ export function CancelPlanButton(props: {
           </SheetTitle>
         </SheetHeader>
 
-        {props.currentPlan === "pro" ? (
+        {props.billingStatus === "invalidPayment" ? (
+          <UnpaidInvoicesWarning teamSlug={props.teamSlug} />
+        ) : props.currentPlan === "pro" ? (
           <ProPlanCancelPlanSheetContent />
         ) : (
           <CancelPlanSheetContent
@@ -115,6 +119,28 @@ export function CancelPlanButton(props: {
   );
 }
 
+function UnpaidInvoicesWarning({ teamSlug }: { teamSlug: string }) {
+  return (
+    <div>
+      <h2 className="mb-1 font-semibold text-2xl tracking-tight">
+        Cancel Plan
+      </h2>
+      <p className="mb-5 text-muted-foreground text-sm">
+        You have unpaid invoices. Please pay them before cancelling your plan.
+      </p>
+
+      <Button variant="outline" asChild className="w-full gap-2 bg-card">
+        <Link
+          href={`/team/${teamSlug}/~/settings/invoices?status=open`}
+          target="_blank"
+        >
+          See Invoices
+        </Link>
+      </Button>
+    </div>
+  );
+}
+
 function ProPlanCancelPlanSheetContent() {
   return (
     <div>
diff --git a/apps/dashboard/src/components/settings/Account/Billing/Pricing.tsx b/apps/dashboard/src/components/settings/Account/Billing/Pricing.tsx
index 7a8e5592054..a7543ee2da1 100644
--- a/apps/dashboard/src/components/settings/Account/Billing/Pricing.tsx
+++ b/apps/dashboard/src/components/settings/Account/Billing/Pricing.tsx
@@ -91,6 +91,7 @@ export const BillingPricing: React.FC<BillingPricingProps> = ({
         {/* Starter */}
         <PricingCard
           billingPlan="starter"
+          billingStatus={team.billingStatus}
           current={validTeamPlan === "starter"}
           cta={
             starterCta?.type === "checkout"
@@ -114,6 +115,7 @@ export const BillingPricing: React.FC<BillingPricingProps> = ({
         {/* Growth */}
         <PricingCard
           billingPlan="growth"
+          billingStatus={team.billingStatus}
           activeTrialEndsAt={
             validTeamPlan === "growth" ? trialPeriodEndedAt : undefined
           }
@@ -140,6 +142,7 @@ export const BillingPricing: React.FC<BillingPricingProps> = ({
         {/* Accelerate */}
         <PricingCard
           billingPlan="accelerate"
+          billingStatus={team.billingStatus}
           teamSlug={team.slug}
           current={validTeamPlan === "accelerate"}
           cta={
@@ -163,6 +166,7 @@ export const BillingPricing: React.FC<BillingPricingProps> = ({
         {/* Scale */}
         <PricingCard
           billingPlan="scale"
+          billingStatus={team.billingStatus}
           teamSlug={team.slug}
           current={validTeamPlan === "scale"}
           cta={