name: flowglad-pricing-ui
description: Build pricing pages, pricing cards, and plan displays with Flowglad. Use this skill when creating pricing tables, displaying subscription options, or building plan comparison interfaces.
license: MIT
metadata:
author: flowglad
version: "1.0.0"

Flowglad Pricing UI

Abstract

Comprehensive guide for building pricing pages, pricing cards, and plan displays with Flowglad. Covers loading states, accessing pricing data through helper functions, formatting prices correctly, highlighting current subscriptions, implementing billing interval toggles, and responsive layout patterns.

Table of Contents

1. Loading States — CRITICAL
2. 1.1 Wait for pricingModel Before Rendering
3. 1.2 Public Pricing Pages with usePricingModel
4. Accessing Pricing Data — HIGH
5. 2.1 Use getProduct and getPrice Helpers
6. 2.2 Filter Products for Display
7. Building Pricing Cards — MEDIUM
8. 3.1 Format Prices from Cents
9. 3.2 Display Billing Interval
10. 3.3 Extract and Display Features
11. Current Plan Highlighting — MEDIUM
12. 4.1 Detect Current Subscription
13. 4.2 Disable or Style Current Plan
14. Billing Interval Toggle — MEDIUM
15. 5.1 Monthly/Annual Toggle Pattern
16. 5.2 Filter Prices by Interval
17. Responsive Layout — LOW
18. 6.1 Grid Layout for Pricing Cards

1. Loading States

Impact: CRITICAL

The pricing model loads asynchronously. Rendering before data is available causes visual flicker, incorrect UI states, or hydration mismatches.

1.1 Wait for pricingModel Before Rendering

Impact: CRITICAL (prevents flash of incorrect content)

Always check that billing data has loaded before rendering pricing UI. The pricingModel is null or undefined until the billing data loads.

Incorrect: renders empty or broken UI while loading

function PricingPage() {
  const billing = useBilling()

  // BUG: pricingModel is undefined while loading!
  // This renders empty pricing grid, then re-renders when data arrives
  const products = billing.pricingModel?.products ?? []

  return (
    <div className="pricing-grid">
      {products.map((product) => (
        <PricingCard key={product.id} product={product} />
      ))}
    </div>
  )
}

Users see an empty pricing page that suddenly fills in, causing layout shift and poor UX.

Correct: show loading state until data is ready

function PricingPage() {
  const billing = useBilling()

  // Wait for billing to load
  if (!billing.loaded) {
    return <PricingPageSkeleton />
  }

  // Handle error state
  if (billing.errors) {
    return <div>Unable to load pricing. Please try again.</div>
  }

  // Now safe to access pricingModel
  const products = billing.pricingModel?.products ?? []

  return (
    <div className="pricing-grid">
      {products.map((product) => (
        <PricingCard key={product.id} product={product} />
      ))}
    </div>
  )
}

Alternative: early return pattern

function PricingPage() {
  const billing = useBilling()

  if (!billing.loaded || billing.errors || !billing.pricingModel) {
    return <PricingPageSkeleton />
  }

  // TypeScript now knows pricingModel is defined
  const { products } = billing.pricingModel

  return (
    <div className="pricing-grid">
      {products.map((product) => (
        <PricingCard key={product.id} product={product} />
      ))}
    </div>
  )
}

1.2 Public Pricing Pages with usePricingModel

Impact: CRITICAL (enables unauthenticated pricing pages)

For public pricing pages that don't require authentication, use the usePricingModel() hook instead of useBilling(). This returns only the pricing data without requiring a logged-in user.

Incorrect: uses useBilling for public page

// Public pricing page - no user logged in
function PublicPricingPage() {
  // BUG: useBilling requires authentication context
  // Will fail or return empty data for unauthenticated users
  const billing = useBilling()

  if (!billing.loaded) return <div>Loading...</div>

  return <PricingDisplay products={billing.pricingModel?.products} />
}

Correct: uses usePricingModel for public pages

import { usePricingModel } from '@flowglad/nextjs'

function PublicPricingPage() {
  // Works without authentication
  const pricingModel = usePricingModel()

  // Returns null while loading
  if (!pricingModel) {
    return <PricingPageSkeleton />
  }

  return (
    <div className="pricing-grid">
      {pricingModel.products.map((product) => {
        const defaultPrice = product.defaultPrice ?? product.prices?.[0]

        return (
          <article key={product.slug}>
            <h3>{product.name}</h3>
            <p>{product.description}</p>
            {defaultPrice && (
              <p>
                ${(defaultPrice.unitPrice / 100).toFixed(2)}
                {defaultPrice.intervalUnit && `/${defaultPrice.intervalUnit}`}
              </p>
            )}
          </article>
        )
      })}
    </div>
  )
}

When to use each hook:

• useBilling() - Authenticated pages where you need subscription status, checkout, or user-specific data
• usePricingModel() - Public pricing pages, marketing sites, or anywhere you just need to display plans

2. Accessing Pricing Data

Impact: HIGH

Flowglad provides helper functions to access products and prices by slug. Using these helpers is more reliable than manual array lookups.

2.1 Use getProduct and getPrice Helpers

Impact: HIGH (prevents runtime errors, cleaner code)

The billing object provides getProduct() and getPrice() helper functions that look up items by slug. Use these instead of manually searching arrays.

Incorrect: manual array lookup

function UpgradeButton({ targetPriceSlug }: { targetPriceSlug: string }) {
  const billing = useBilling()

  if (!billing.loaded) return null

  // Fragile: searches across all products, easy to get wrong
  const targetPrice = billing.pricingModel?.products
    .flatMap((p) => p.prices)
    .find((price) => price.slug === targetPriceSlug)

  if (!targetPrice) return null

  return <button>Upgrade to {targetPrice.name}</button>
}

Correct: use getPrice helper

function UpgradeButton({ targetPriceSlug }: { targetPriceSlug: string }) {
  const billing = useBilling()

  if (!billing.loaded) return null

  // Clean: helper does the lookup efficiently
  const targetPrice = billing.getPrice(targetPriceSlug)

  if (!targetPrice) return null

  return <button>Upgrade to {targetPrice.name}</button>
}

Same pattern for products:

function ProductFeatures({ productSlug }: { productSlug: string }) {
  const billing = useBilling()

  if (!billing.loaded) return null

  // Use getProduct helper
  const product = billing.getProduct(productSlug)

  if (!product) return null

  return (
    <ul>
      {product.features.map((feature) => (
        <li key={feature.id}>{feature.name}</li>
      ))}
    </ul>
  )
}

2.2 Filter Products for Display

Impact: HIGH (shows only relevant products)

Not all products should appear on pricing pages. Filter out default/free products and products without active prices.

Incorrect: displays all products including internal ones

function PricingGrid() {
  const billing = useBilling()

  if (!billing.loaded || !billing.pricingModel) return null

  // BUG: Shows ALL products, including free tier and inactive products
  return (
    <div>
      {billing.pricingModel.products.map((product) => (
        <PricingCard key={product.id} product={product} />
      ))}
    </div>
  )
}

Correct: filter to displayable products

function PricingGrid() {
  const billing = useBilling()

  if (!billing.loaded || !billing.pricingModel) return null

  // Filter products for display
  const displayProducts = billing.pricingModel.products.filter((product) => {
    // Skip default/free tier products
    if (product.default === true) return false

    // Only show products with active subscription prices
    const hasActivePrice = product.prices.some(
      (price) => price.type === 'subscription' && price.active === true
    )

    return hasActivePrice
  })

  return (
    <div>
      {displayProducts.map((product) => (
        <PricingCard key={product.id} product={product} />
      ))}
    </div>
  )
}

Transform to UI-friendly format:

interface PricingPlan {
  name: string
  description?: string
  displayPrice: string
  slug: string
  features: string[]
  unitPrice: number
}

function transformProductsToPricingPlans(
  pricingModel: PricingModel | null | undefined
): PricingPlan[] {
  if (!pricingModel?.products) return []

  return pricingModel.products
    .filter((product) => {
      if (product.default === true) return false
      return product.prices.some(
        (p) => p.type === 'subscription' && p.active === true
      )
    })
    .map((product) => {
      const price = product.prices.find(
        (p) => p.type === 'subscription' && p.active === true
      )

      if (!price?.slug) return null

      return {
        name: product.name,
        description: product.description,
        displayPrice: `$${(price.unitPrice / 100).toFixed(2)}`,
        slug: price.slug,
        features: product.features.map((f) => f.name).filter(Boolean),
        unitPrice: price.unitPrice,
      }
    })
    .filter((plan): plan is PricingPlan => plan !== null)
    .sort((a, b) => a.unitPrice - b.unitPrice)
}

3. Building Pricing Cards

Impact: MEDIUM

Pricing cards display product information with proper formatting. Getting price formatting and interval display right is essential for clear communication.

3.1 Format Prices from Cents

Impact: MEDIUM (prevents displaying wrong amounts)

Flowglad stores prices in cents (e.g., 1000 = $10.00). Always convert to dollars for display.

Incorrect: displays cents as dollars

function PriceDisplay({ price }: { price: Price }) {
  // BUG: Shows "$1000" instead of "$10.00"
  return <span>${price.unitPrice}</span>
}

Correct: convert cents to dollars

function PriceDisplay({ price }: { price: Price }) {
  const dollars = (price.unitPrice / 100).toFixed(2)
  return <span>${dollars}</span>
}

Helper function for consistent formatting:

function formatPriceFromCents(cents: number): string {
  return `$${(cents / 100).toFixed(2)}`
}

// Usage
function PriceDisplay({ price }: { price: Price }) {
  return <span>{formatPriceFromCents(price.unitPrice)}</span>
}

With locale-aware formatting:

function formatPriceFromCents(
  cents: number,
  currency: string = 'USD',
  locale: string = 'en-US'
): string {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency,
  }).format(cents / 100)
}

3.2 Display Billing Interval

Impact: MEDIUM (clarifies subscription terms)

Subscription prices have intervalUnit (day, month, year) and intervalCount properties. Display these clearly.

Incorrect: ignores billing interval

function PriceDisplay({ price }: { price: SubscriptionPrice }) {
  // Confusing: Is this $10 total? Per month? Per year?
  return <span>${(price.unitPrice / 100).toFixed(2)}</span>
}

Correct: shows billing interval

function PriceDisplay({ price }: { price: SubscriptionPrice }) {
  const amount = (price.unitPrice / 100).toFixed(2)

  // Format interval display
  let intervalLabel = ''
  if (price.intervalUnit) {
    if (price.intervalCount === 1) {
      intervalLabel = `/${price.intervalUnit}`
    } else {
      intervalLabel = ` every ${price.intervalCount} ${price.intervalUnit}s`
    }
  }

  return (
    <span>
      ${amount}
      {intervalLabel}
    </span>
  )
}

// Renders: "$10.00/month" or "$99.00/year" or "$5.00 every 2 weeks"

Helper function:

function formatSubscriptionPrice(price: SubscriptionPrice): string {
  const amount = (price.unitPrice / 100).toFixed(2)

  if (!price.intervalUnit) {
    return `$${amount}`
  }

  if (price.intervalCount === 1) {
    return `$${amount}/${price.intervalUnit}`
  }

  return `$${amount} every ${price.intervalCount} ${price.intervalUnit}s`
}

3.3 Extract and Display Features

Impact: MEDIUM (shows value proposition)

Products have a features array. Extract and display feature names in pricing cards.

Incorrect: doesn't handle missing feature names

function FeatureList({ product }: { product: Product }) {
  return (
    <ul>
      {product.features.map((feature) => (
        // BUG: feature.name might be undefined
        <li key={feature.id}>{feature.name}</li>
      ))}
    </ul>
  )
}

Correct: filter to features with names

function FeatureList({ product }: { product: Product }) {
  // Filter to features that have names
  const displayFeatures = product.features.filter(
    (feature): feature is Feature & { name: string } =>
      typeof feature.name === 'string' && feature.name.length > 0
  )

  if (displayFeatures.length === 0) {
    return null
  }

  return (
    <ul>
      {displayFeatures.map((feature) => (
        <li key={feature.id}>{feature.name}</li>
      ))}
    </ul>
  )
}

4. Current Plan Highlighting

Impact: MEDIUM

When displaying pricing to authenticated users, highlight which plan they're currently on to help them understand their options.

4.1 Detect Current Subscription

Impact: MEDIUM (helps users understand their status)

Use the current subscription's price ID to determine which pricing card represents the user's current plan.

Incorrect: compares product names (unreliable)

function isPlanCurrent(product: Product, billing: LoadedBillingContext) {
  // BUG: Product names might not be unique, or might change
  return billing.currentSubscription?.product?.name === product.name
}

Correct: compares price IDs

function isPlanCurrent(priceSlug: string, billing: LoadedBillingContext) {
  // No current subscription = no current plan
  if (!billing.currentSubscriptions?.length) {
    return false
  }

  // Get the price by slug
  const price = billing.getPrice(priceSlug)
  if (!price) {
    return false
  }

  // Check if any current subscription uses this price
  const currentPriceIds = new Set(
    billing.currentSubscriptions.map((sub) => sub.priceId)
  )

  return currentPriceIds.has(price.id)
}

Usage in a component:

function PricingCard({
  plan,
  isCurrentPlan,
}: {
  plan: PricingPlan
  isCurrentPlan: boolean
}) {
  return (
    <div className={isCurrentPlan ? 'border-primary' : 'border-gray-200'}>
      <h3>{plan.name}</h3>
      <p>{plan.displayPrice}</p>
      {isCurrentPlan && <span className="badge">Current Plan</span>}
    </div>
  )
}

function PricingGrid() {
  const billing = useBilling()

  if (!billing.loaded || !billing.pricingModel) return null

  const plans = transformProductsToPricingPlans(billing.pricingModel)

  return (
    <div className="grid grid-cols-3 gap-4">
      {plans.map((plan) => (
        <PricingCard
          key={plan.slug}
          plan={plan}
          isCurrentPlan={isPlanCurrent(plan.slug, billing)}
        />
      ))}
    </div>
  )
}

4.2 Disable or Style Current Plan

Impact: MEDIUM (prevents confusing interactions)

The "current plan" card should not have an active checkout button. Either disable or restyle the action.

Incorrect: same button for all plans

function PricingCard({ plan }: { plan: PricingPlan }) {
  const billing = useBilling()

  const handleUpgrade = async () => {
    // BUG: Allows clicking to "upgrade" to current plan
    await billing.createCheckoutSession({
      priceSlug: plan.slug,
      successUrl: window.location.origin,
      cancelUrl: window.location.href,
      autoRedirect: true,
    })
  }

  return (
    <div>
      <h3>{plan.name}</h3>
      <button onClick={handleUpgrade}>Get Started</button>
    </div>
  )
}

Correct: disable button for current plan

function PricingCard({
  plan,
  isCurrentPlan,
}: {
  plan: PricingPlan
  isCurrentPlan: boolean
}) {
  const billing = useBilling()
  const [isLoading, setIsLoading] = useState(false)

  const handleUpgrade = async () => {
    if (isCurrentPlan || isLoading) return

    setIsLoading(true)
    try {
      await billing.createCheckoutSession({
        priceSlug: plan.slug,
        successUrl: `${window.location.origin}/dashboard?upgraded=true`,
        cancelUrl: window.location.href,
        autoRedirect: true,
      })
    } finally {
      setIsLoading(false)
    }
  }

  return (
    <div className={isCurrentPlan ? 'border-primary' : ''}>
      <h3>{plan.name}</h3>
      <p>{plan.displayPrice}</p>
      <button
        onClick={handleUpgrade}
        disabled={isCurrentPlan || isLoading}
        className={isCurrentPlan ? 'opacity-50 cursor-not-allowed' : ''}
      >
        {isCurrentPlan ? 'Current Plan' : isLoading ? 'Loading...' : 'Get Started'}
      </button>
    </div>
  )
}

5. Billing Interval Toggle

Impact: MEDIUM

Many pricing pages let users toggle between monthly and annual billing to compare options.

5.1 Monthly/Annual Toggle Pattern

Impact: MEDIUM (improves comparison shopping)

Implement a toggle that filters prices by billing interval.

Basic implementation:

type BillingInterval = 'month' | 'year'

function PricingPage() {
  const billing = useBilling()
  const [interval, setInterval] = useState<BillingInterval>('month')

  if (!billing.loaded || !billing.pricingModel) {
    return <PricingPageSkeleton />
  }

  return (
    <div>
      <div className="flex gap-2 mb-8">
        <button
          onClick={() => setInterval('month')}
          className={interval === 'month' ? 'bg-primary' : 'bg-gray-200'}
        >
          Monthly
        </button>
        <button
          onClick={() => setInterval('year')}
          className={interval === 'year' ? 'bg-primary' : 'bg-gray-200'}
        >
          Annual
        </button>
      </div>

      <PricingGrid interval={interval} pricingModel={billing.pricingModel} />
    </div>
  )
}

5.2 Filter Prices by Interval

Impact: MEDIUM (shows correct prices for selected interval)

When displaying prices, filter to only show prices matching the selected billing interval.

Incorrect: shows all prices regardless of interval

function PricingGrid({
  interval,
  pricingModel,
}: {
  interval: BillingInterval
  pricingModel: PricingModel
}) {
  return (
    <div>
      {pricingModel.products.map((product) => {
        // BUG: Shows first price regardless of interval selection
        const price = product.prices[0]

        return (
          <PricingCard key={product.id} product={product} price={price} />
        )
      })}
    </div>
  )
}

Correct: filter prices by interval

function PricingGrid({
  interval,
  pricingModel,
}: {
  interval: BillingInterval
  pricingModel: PricingModel
}) {
  const plans = pricingModel.products
    .filter((product) => !product.default)
    .map((product) => {
      // Find the price matching the selected interval
      const price = product.prices.find(
        (p) =>
          p.type === 'subscription' &&
          p.active === true &&
          p.intervalUnit === interval &&
          (p.intervalCount === 1 || p.intervalCount === undefined)
      )

      if (!price) return null

      return {
        product,
        price,
        displayPrice: formatSubscriptionPrice(price),
      }
    })
    .filter(Boolean)

  return (
    <div className="grid grid-cols-3 gap-4">
      {plans.map(({ product, price, displayPrice }) => (
        <PricingCard
          key={product.id}
          name={product.name}
          description={product.description}
          price={displayPrice}
          priceSlug={price.slug}
          features={product.features}
        />
      ))}
    </div>
  )
}

6. Responsive Layout

Impact: LOW

Pricing grids should adapt to different screen sizes for optimal viewing.

6.1 Grid Layout for Pricing Cards

Impact: LOW (improves mobile experience)

Use CSS grid with responsive breakpoints to adjust the number of columns.

Basic responsive grid:

function PricingGrid({ plans }: { plans: PricingPlan[] }) {
  return (
    <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
      {plans.map((plan) => (
        <PricingCard key={plan.slug} plan={plan} />
      ))}
    </div>
  )
}

Centered layout for fewer plans:

function PricingGrid({ plans }: { plans: PricingPlan[] }) {
  // Center cards when fewer than 3 plans
  const gridClass =
    plans.length <= 2
      ? 'flex flex-wrap justify-center gap-6'
      : 'grid gap-6 md:grid-cols-2 lg:grid-cols-3'

  return (
    <div className={gridClass}>
      {plans.map((plan) => (
        <PricingCard key={plan.slug} plan={plan} />
      ))}
    </div>
  )
}

Full-width cards on mobile:

function PricingCard({ plan }: { plan: PricingPlan }) {
  return (
    <div className="w-full md:max-w-sm rounded-lg border p-6">
      <h3 className="text-xl font-semibold">{plan.name}</h3>
      <p className="text-3xl font-bold my-4">{plan.displayPrice}</p>

      <ul className="space-y-2 mb-6">
        {plan.features.map((feature, index) => (
          <li key={index} className="flex items-center gap-2">
            <CheckIcon className="h-4 w-4 text-green-500" />
            <span>{feature}</span>
          </li>
        ))}
      </ul>

      <button className="w-full py-2 px-4 bg-primary text-white rounded">
        Get Started
      </button>
    </div>
  )
}

References

1. Flowglad Documentation
2. Flowglad React SDK