Skip to main content
  • Next.js
  • React
  • Server
  • Express

​
Installation

npm install @flowglad/nextjs

​
Requirements

  • React 18 or 19
  • Next.js 14 or 15

​
Quick Start

​
1. Set Up Environment Variables

Add your Flowglad API key to your environment:
.env
FLOWGLAD_SECRET_KEY="sk_test_..."

​
2. Create Server Client

Create a Flowglad server factory function in a shared file:
utils/flowglad.ts
import { FlowgladServer } from '@flowglad/nextjs/server'

export const flowglad = (customerExternalId: string) => {
  // customerExternalId is the ID from YOUR app's database, NOT Flowglad's customer ID
  return new FlowgladServer({
    customerExternalId,
    getCustomerDetails: async (externalId) => {
      // Fetch customer details from YOUR database using YOUR app's ID
      const user = await db.users.findOne({ id: externalId })
      if (!user) {
        throw new Error('Customer not found')
      }
      return {
        email: user.email,
        name: user.name,
      }
    },
  })
}
Important: customerExternalId is the ID from your app’s database (e.g., user.id or organization.id), not Flowglad’s customer ID.B2C apps: Pass user.id as customerExternalId
B2B apps: Pass organization.id or team.id as customerExternalId

​
3. Create API Route Handler

app/api/flowglad/[...path]/route.ts (App Router)
import { nextRouteHandler } from '@flowglad/nextjs/server'
import { flowglad } from '@/utils/flowglad'

export const { GET, POST } = nextRouteHandler({
  flowglad,
  getCustomerExternalId: async (req) => {
    // Extract customerExternalId from your auth/session
    // This should be YOUR app's user/organization ID, NOT Flowglad's customer ID
    // For B2C: return user.id (from your database)
    // For B2B: return organization.id (from your database)
    const userId = await getUserIdFromRequest(req)
    if (!userId) {
      throw new Error('User not authenticated')
    }
    return userId
  },
})

​
4. Wrap Your App with FlowgladProvider

import { FlowgladProvider } from '@flowglad/nextjs'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <FlowgladProvider loadBilling={true}>
          {children}
        </FlowgladProvider>
      </body>
    </html>
  )
}

​
5. Use the Billing Hook

import { useBilling } from '@flowglad/nextjs'

export default function BillingPage() {
  const { checkFeatureAccess, createCheckoutSession } = useBilling()

  if (!checkFeatureAccess) {
    return <div>Loading...</div>
  }

  if (checkFeatureAccess('premium_feature')) {
    return <div>You have access to premium features!</div>
  }

  return (
    <button
      onClick={() =>
        createCheckoutSession({
          priceId: 'price_123',
          successUrl: window.location.href,
          cancelUrl: window.location.href,
          autoRedirect: true,
        })
      }
    >
      Upgrade to Premium
    </button>
  )
}
Read more about the Flowglad Next.js SDK at the Next.js documentation page