Skip to main content
The best time to ask for an upgrade is when a customer is getting real value from your product. Upgrade nudges appear automatically when usage approaches a limit — converting engaged users at the perfect moment instead of hitting them with a hard paywall.

​
How it works

  1. The SDK calls checkUsage() to see if the user is near a limit
  2. If usage exceeds the threshold (default: 80%), BillingOS returns a nudge trigger
  3. The UpgradeNudge component displays the prompt with a suggested plan

​
Automatic nudge

import { UpgradeNudge, useBillingOS } from "@billingos/sdk";
import { useQuery } from "@tanstack/react-query";

function NudgeBanner() {
  const { client } = useBillingOS();

  const { data } = useQuery({
    queryKey: ["usage-check"],
    queryFn: () => client!.checkUsage(),
    enabled: !!client,
    refetchInterval: 60000, // Check every minute
  });

  if (!data?.shouldShowNudge || !data.trigger) return null;

  return (
    <UpgradeNudge
      trigger={data.trigger}
      style="banner"
      onUpgrade={(priceId) => {
        router.push(`/pricing?plan=${priceId}`);
      }}
    />
  );
}
Upgrade nudge

​
Display styles

StyleBest for
bannerTop of page, non-intrusive, always visible
toastBottom-right notification, auto-dismissible
modalCentered dialog, high visibility, requires action
// Banner at the top of a page
<UpgradeNudge trigger={trigger} style="banner" />

// Toast notification that auto-dismisses
<UpgradeNudge trigger={trigger} style="toast" autoDismiss={10000} />

// Modal for critical limits
<UpgradeNudge trigger={trigger} style="modal" />

​
Manual upgrade prompts

For static placement (not triggered by usage), use UpgradePrompt: 
import { UpgradePrompt } from "@billingos/sdk";

<UpgradePrompt
  feature="advanced_analytics"
  title="Unlock advanced analytics"
  description="Get deeper insights with the Pro plan."
  onUpgradeClick={() => router.push("/pricing")}
/>

​
Compact variant

For inline placement in toolbars or sidebars: 
import { CompactUpgradePrompt } from "@billingos/sdk";

<CompactUpgradePrompt
  feature="custom_reports"
  onUpgradeClick={() => setCheckoutOpen(true)}
/>

​
Combine with FeatureGate

Show context-aware upgrade prompts when a feature is locked: 
import { FeatureGate, UpgradePrompt } from "@billingos/sdk";

<FeatureGate
  feature="custom_reports"
  fallback={
    <UpgradePrompt
      feature="custom_reports"
      title="Custom reports"
      description="Available on Pro and Enterprise plans."
      onUpgradeClick={() => setCheckoutOpen(true)}
    />
  }
>
  <ReportBuilder />
</FeatureGate>
See the UpgradeNudge and UpgradePrompt component references for all props.