feat: merge subscription credits with API credits UI updates

- Add api_credit_balance field to BillingStatus type
- Show API credit balance in CreditUsage when plan is >=75% used
- Add 'Buy API Credits' button in UpgradePromptDialog for paid users
- Update BillingStatus messaging to mention API credits option
- Add FAQ about using subscription for API access
- Update API Access feature descriptions in pricing config
- Update ApiCreditsSection description text
- Add api_settings URL param to open API settings dialog

Closes #406

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: AnthonyRonning

frontend/src/billing/billingApi.ts

@@ -18,6 +18,7 @@ export type BillingStatus = {
   total_tokens: number | null;
   used_tokens: number | null;
   usage_reset_date: string | null;
+  api_credit_balance?: number;
 };
 
 type BillingRecurringInfo = {

frontend/src/components/BillingStatus.tsx

@@ -50,6 +50,9 @@ export function BillingStatus() {
   const isFree = billingStatus.product_name.toLowerCase().includes("free");
   const isMax = billingStatus.product_name.toLowerCase().includes("max");
 
+  const hasApiAccess =
+    billingStatus.product_name?.toLowerCase().includes("pro") || isMax || isTeamPlan;
+
   const getChatsText = () => {
     if (isFree) {
       if (billingStatus.chats_remaining === null || billingStatus.chats_remaining <= 0) {
@@ -59,9 +62,13 @@ export function BillingStatus() {
     }
     if (!billingStatus.can_chat) {
       if (isMax) {
-        return "Contact us to increase your limits";
+        return hasApiAccess
+          ? "Purchase API credits or contact us to increase limits"
+          : "Contact us to increase your limits";
       }
-      return "You've run out of messages, upgrade to keep chatting!";
+      return hasApiAccess
+        ? "Upgrade your plan or purchase API credits to keep chatting!"
+        : "You've run out of messages, upgrade to keep chatting!";
     }
 
     // Show team name for team plans

frontend/src/components/CreditUsage.tsx

@@ -22,17 +22,25 @@ export function CreditUsage() {
     return null;
   }
 
+  // Check if user has API credits - always show if they have any
+  const hasApiCredits =
+    billingStatus.api_credit_balance !== undefined && billingStatus.api_credit_balance > 0;
+
   // Set bar color based on usage
   const getBarColor = () => {
     if (percentUsed >= 90) return "rgb(239, 68, 68)"; // Tailwind red-500
     if (percentUsed >= 75) return "rgb(245, 158, 11)"; // Tailwind amber-500
     return "rgb(16, 185, 129)"; // Tailwind emerald-500
   };
 
+  const formatCredits = (credits: number) => {
+    return new Intl.NumberFormat("en-US").format(credits);
+  };
+
   return (
     <div className="px-2 py-2 text-xs text-muted-foreground">
       <div className="mb-1 flex justify-between">
-        <span>Credit Usage</span>
+        <span>Plan Credits</span>
         <span>{roundedPercent}%</span>
       </div>
       <div className="h-2.5 w-full overflow-hidden rounded-full bg-muted">
@@ -44,8 +52,13 @@ export function CreditUsage() {
           }}
         />
       </div>
-      <div className="mt-1 text-xs text-right">
-        {formatResetDate(billingStatus.usage_reset_date)}
+      <div className="mt-1 flex justify-between text-xs">
+        {hasApiCredits && (
+          <span>+ {formatCredits(billingStatus.api_credit_balance ?? 0)} API credits</span>
+        )}
+        <span className={hasApiCredits ? "" : "ml-auto"}>
+          {formatResetDate(billingStatus.usage_reset_date)}
+        </span>
       </div>
     </div>
   );

frontend/src/components/UpgradePromptDialog.tsx

@@ -16,7 +16,8 @@ import {
   FileText,
   Gauge,
   MessageCircle,
-  Globe
+  Globe,
+  Coins
 } from "lucide-react";
 import { useNavigate } from "@tanstack/react-router";
 import { useLocalState } from "@/state/useLocalState";
@@ -42,6 +43,11 @@ export function UpgradePromptDialog({
     navigate({ to: "/pricing" });
   };
 
+  const handleBuyCredits = () => {
+    onOpenChange(false);
+    navigate({ to: "/", search: { api_settings: true } });
+  };
+
   const handleNewChat = () => {
     onOpenChange(false);
     // Trigger new chat event
@@ -57,6 +63,7 @@ export function UpgradePromptDialog({
   const isFreeTier = !localState.billingStatus?.product_name || currentPlan === "free";
   const isPro = currentPlan.includes("pro") && !currentPlan.includes("max");
   const isMax = currentPlan.includes("max");
+  const hasApiAccess = isPro || isMax || currentPlan.includes("team");
 
   const getNextPlan = () => {
     if (isFreeTier) return "Pro";
@@ -130,8 +137,8 @@ export function UpgradePromptDialog({
         description: isFreeTier
           ? "You've reached your daily free tier limit. Upgrade to Pro for unlimited daily usage."
           : isPro
-            ? "You've reached your Pro plan's monthly limit. Upgrade to Max for 10x more usage."
-            : "You've reached your monthly usage limit. Please wait for the next billing cycle.",
+            ? "You've reached your Pro plan's monthly limit. Upgrade to Max for 10x more usage, or purchase API credits to continue chatting."
+            : "You've reached your monthly usage limit. Purchase API credits to continue chatting, or wait for the next billing cycle.",
         requiredPlan: nextPlan,
         benefits: isFreeTier
           ? [
@@ -147,11 +154,12 @@ export function UpgradePromptDialog({
                 "10x more monthly messages with Max plan",
                 "Access to all premium models including DeepSeek R1",
                 "Highest priority during peak times",
-                "Maximum rate limits for power users"
+                "Maximum rate limits for power users",
+                "Or purchase API credits to keep chatting now"
               ]
             : [
                 "You're already on our highest individual plan",
-                "Consider Team plans for shared usage",
+                "Purchase API credits to extend your usage",
                 "Monthly usage automatically refreshes",
                 "Contact support for custom enterprise plans"
               ]
@@ -230,23 +238,30 @@ export function UpgradePromptDialog({
           ) : null}
         </div>
 
-        <DialogFooter className="gap-2 sm:gap-0">
+        <DialogFooter className="flex flex-col gap-2 sm:flex-col sm:justify-stretch sm:space-x-0">
+          {(info.requiredPlan !== "Max" || !isMax) && (
+            <Button onClick={handleUpgrade} className="w-full gap-2">
+              <Sparkles className="h-4 w-4" />
+              {isFreeTier ? "Upgrade to Pro" : isPro ? "Upgrade to Max" : "View Plans"}
+            </Button>
+          )}
+          {/* Show Buy Credits button for paid users hitting usage limits */}
+          {feature === "usage" && hasApiAccess && (
+            <Button variant="outline" onClick={handleBuyCredits} className="w-full gap-2">
+              <Coins className="h-4 w-4" />
+              Buy API Credits
+            </Button>
+          )}
           {/* Show "Start New Chat" for free tier conversation limit, "Maybe Later" for others */}
           {feature === "tokens" && isFreeTier ? (
-            <Button variant="outline" onClick={handleNewChat}>
+            <Button variant="ghost" onClick={handleNewChat} className="w-full">
               Start New Chat
             </Button>
           ) : (
-            <Button variant="outline" onClick={() => onOpenChange(false)}>
+            <Button variant="ghost" onClick={() => onOpenChange(false)} className="w-full">
               Maybe Later
             </Button>
           )}
-          {(info.requiredPlan !== "Max" || !isMax) && (
-            <Button onClick={handleUpgrade} className="gap-2">
-              <Sparkles className="h-4 w-4" />
-              {isFreeTier ? "Upgrade to Pro" : isPro ? "Upgrade to Max" : "View Plans"}
-            </Button>
-          )}
         </DialogFooter>
       </DialogContent>
     </Dialog>

frontend/src/components/apikeys/ApiCreditsSection.tsx

@@ -193,7 +193,7 @@ export function ApiCreditsSection({ showSuccessMessage = false }: ApiCreditsSect
               {formatCredits(creditBalance?.balance || 0)}
             </p>
             <p className="text-xs text-muted-foreground mt-1">
-              $1 per 1,000 credits • Use for API requests
+              $1 per 1,000 credits • Extends your subscription when plan credits run out
             </p>
           </div>
         </div>

frontend/src/components/apikeys/ApiKeyDashboard.tsx

@@ -162,9 +162,9 @@ export function ApiKeyDashboard({ showCreditSuccessMessage = false }: ApiKeyDash
                   <Rocket className="h-5 w-5 text-green-500" />
                 </div>
                 <div>
-                  <h3 className="font-semibold">Pay-As-You-Go Credits</h3>
+                  <h3 className="font-semibold">Extend Your Subscription</h3>
                   <p className="text-sm text-muted-foreground">
-                    Purchase credits for API usage at just $1 per 1,000 credits
+                    Purchase API credits to extend your usage when plan credits run out
                   </p>
                 </div>
               </div>
@@ -183,7 +183,7 @@ export function ApiKeyDashboard({ showCreditSuccessMessage = false }: ApiKeyDash
             </Button>
 
             <p className="text-xs text-muted-foreground text-center">
-              Unlock API access, increased limits, and premium features
+              Use your plan credits via API, and purchase extra credits to extend your usage
             </p>
           </div>
         </div>

frontend/src/config/pricingConfig.tsx

@@ -139,7 +139,7 @@ export const PRICING_PLANS: PricingPlan[] = [
         icon: <Check className="w-4 h-4 text-green-500" />
       },
       {
-        text: "API Access",
+        text: "API Access (use plan credits via API)",
         included: true,
         icon: <Check className="w-4 h-4 text-green-500" />
       }
@@ -189,7 +189,7 @@ export const PRICING_PLANS: PricingPlan[] = [
         icon: <Check className="w-4 h-4 text-green-500" />
       },
       {
-        text: "API Access",
+        text: "API Access (use plan credits via API)",
         included: true,
         icon: <Check className="w-4 h-4 text-green-500" />
       }
@@ -248,7 +248,7 @@ export const PRICING_PLANS: PricingPlan[] = [
         icon: <Check className="w-4 h-4 text-green-500" />
       },
       {
-        text: "API Access",
+        text: "API Access (use plan credits via API)",
         included: true,
         icon: <Check className="w-4 h-4 text-green-500" />
       }

frontend/src/routes/index.tsx

@@ -20,6 +20,7 @@ type IndexSearchOptions = {
   next?: string;
   team_setup?: boolean;
   credits_success?: boolean;
+  api_settings?: boolean;
 };
 
 function validateSearch(search: Record<string, unknown>): IndexSearchOptions {
@@ -28,7 +29,9 @@ function validateSearch(search: Record<string, unknown>): IndexSearchOptions {
     next: search.next ? (search.next as string) : undefined,
     team_setup: search?.team_setup === true || search?.team_setup === "true" ? true : undefined,
     credits_success:
-      search?.credits_success === true || search?.credits_success === "true" ? true : undefined
+      search?.credits_success === true || search?.credits_success === "true" ? true : undefined,
+    api_settings:
+      search?.api_settings === true || search?.api_settings === "true" ? true : undefined
   };
 }
 
@@ -43,7 +46,7 @@ function Index() {
   const queryClient = useQueryClient();
   const { setBillingStatus, billingStatus } = useLocalState();
 
-  const { login, next, team_setup, credits_success } = Route.useSearch();
+  const { login, next, team_setup, credits_success, api_settings } = Route.useSearch();
 
   // Modal states
   const [teamDialogOpen, setTeamDialogOpen] = useState(false);
@@ -119,6 +122,15 @@ function Index() {
     }
   }, [credits_success, os.auth.user, navigate, queryClient]);
 
+  // Handle api_settings - open API key dialog directly
+  useEffect(() => {
+    if (api_settings && os.auth.user) {
+      setApiKeyDialogOpen(true);
+      // Clear the query param to prevent re-opening on refresh
+      navigate({ to: "/", replace: true });
+    }
+  }, [api_settings, os.auth.user, navigate]);
+
   // Check if guest user needs to pay
   const isGuestUser = os.auth.user?.user.login_method?.toLowerCase() === "guest";
   const isOnFreePlan = billingStatus?.product_name?.toLowerCase().includes("free") ?? false;

frontend/src/routes/pricing.tsx

@@ -156,6 +156,23 @@ function PricingFAQ() {
           </div>
         </details>
 
+        <details className="group">
+          <summary className="cursor-pointer text-lg font-medium hover:text-foreground/80">
+            Can I use my subscription for API access?
+          </summary>
+          <div className="mt-4 text-[hsl(var(--marketing-text-muted))] space-y-2">
+            <p>
+              Yes! Pro, Max, and Team plans include API access. Your subscription credits work
+              seamlessly with the API.
+            </p>
+            <ul className="list-disc list-inside space-y-1 ml-4">
+              <li>Use your plan credits via the API</li>
+              <li>When plan credits run out, API credits kick in automatically</li>
+              <li>Purchase additional API credits to extend your usage anytime</li>
+            </ul>
+          </div>
+        </details>
+
         <details className="group">
           <summary className="cursor-pointer text-lg font-medium hover:text-foreground/80">
             How did you build this?