Billing SDK Components

@auth-gate/react ships drop-in components for the most common billing UI patterns. Each component handles its own data fetching, loading states, and error handling.

PricingTable

Renders a responsive pricing card grid with an interval toggle (monthly / annually). Highlights the recommended plan and shows a CTA button per plan that initiates the checkout flow.

import { PricingTable } from "@auth-gate/react";

export default function PricingPage() {
  return (
    <PricingTable
      onCheckout={(priceId) => {
        // Redirect to checkout or open a modal
        window.location.href = `/checkout?price=${priceId}`;
      }}
    />
  );
}

Props

Name
onCheckout
Type
(priceId: string) => void
Description
Called when a user clicks the CTA button on a plan card. Receives the selected price ID. Use this to redirect to checkout or open the <CheckoutForm />.
Name
highlightedPlanId
Type
string
Description
Optional plan ID to mark as "Recommended" or "Most Popular". Defaults to the plan flagged as recommended in the dashboard.
Name
defaultInterval
Type
'month' | 'year'
Description
Initial billing interval shown in the toggle. Defaults to 'month'.
Name
className
Type
string
Description
Additional CSS class names applied to the outer container.

The component fetches plans from GET /api/proxy/billing/plans. Plans marked as hidden in the dashboard are not returned.

CheckoutForm

Initiates a checkout session for a specific price and renders a payment collection UI. On success, redirects to successUrl. On cancel, redirects to cancelUrl.

import { CheckoutForm } from "@auth-gate/react";

export default function CheckoutPage() {
  return (
    <CheckoutForm
      priceId="price_abc123"
      successUrl="/dashboard?subscribed=true"
      cancelUrl="/pricing"
    />
  );
}

Props

Name
priceId
Type
string
Description
The price ID to check out. Obtained from the plan list or passed from <PricingTable />.
Name
successUrl
Type
string
Description
Where to redirect after a successful payment.
Name
cancelUrl
Type
string
Description
Where to redirect if the user cancels.
Name
promotionCode
Type
string
Description
Optional promotion code to pre-apply at checkout. The discount is displayed in the order summary.
Name
trialDays
Type
number
Description
Override the trial period for this checkout. Only valid if the plan has trials enabled.

The component posts to POST /api/proxy/billing/checkout and renders an embedded Stripe payment element within the AuthGate checkout flow.

SubscriptionManager

Displays the user's current plan, billing period, next invoice amount, and action buttons for canceling or resuming a subscription.

import { SubscriptionManager } from "@auth-gate/react";

function AccountPage() {
  return (
    <SubscriptionManager
      onCanceled={() => {
        console.log("Subscription canceled");
      }}
      onResumed={() => {
        console.log("Subscription resumed");
      }}
    />
  );
}

Props

Name
onCanceled
Type
() => void
Description
Called after the user confirms subscription cancellation.
Name
onResumed
Type
() => void
Description
Called after a paused or pending-cancellation subscription is resumed.
Name
showInvoices
Type
boolean
Description
Whether to render a recent invoices list below the subscription details.
Name
className
Type
string
Description
Additional CSS class names applied to the outer container.

The component fetches from GET /api/proxy/billing/subscription and GET /api/proxy/billing/invoices. Cancel and resume actions call the corresponding proxy endpoints.

BillingGate

Conditionally renders children based on the user's current entitlements. Useful for hiding or showing UI elements based on plan or feature access.

import { BillingGate } from "@auth-gate/react";
import { billing } from "../../authgate.billing";

function AdvancedFeature() {
  return (
    <BillingGate
      requires={{ plan: billing.plans.pro }}  // type-safe — no .key needed
      fallback={<p>Upgrade to Pro to access this feature.</p>}
    >
      <AdvancedAnalyticsDashboard />
    </BillingGate>
  );
}

Props

Name
requires
Type
{ plan?: string; feature?: string }
Description
The entitlement check to perform. Provide plan to require a specific plan or higher, feature to require a specific feature flag, or both to require both conditions.
Name
fallback
Type
React.ReactNode
Description
Content to render when the user does not meet the entitlement requirement. Defaults to null.
Name
children
Type
React.ReactNode
Description
Content to render when the user meets the requirement.

<BillingGate> reads from the entitlements cached by the useEntitlements hook. If entitlements have not been fetched yet, the component renders null until the check resolves. See Entitlements for the full entitlement system documentation.