@flowglad/nextjs

Overview

The Next.js SDK provides a complete integration for both App Router and Pages Router, including server-side utilities and client-side components.

Installation

npm install @flowglad/nextjs

yarn add @flowglad/nextjs

bun add @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, eg. lib/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 (customerExternalId) => {
      // Fetch customer details from YOUR database using YOUR app's ID
      const user = await db.users.findOne({ id: customerExternalId })
      if (!user) {
        throw new Error('Customer not found')
      }
      return {
        email: user.email,
        name: user.name,
      }
    },
  })
}

import { FlowgladServer } from '@flowglad/nextjs/server'
import { auth } from '@/utils/auth'
import { headers } from 'next/headers'

export const flowglad = (customerExternalId: string) => {
  return new FlowgladServer({
    customerExternalId,
    getCustomerDetails: async (customerExternalId) => {
      const session = await auth.api.getSession({
        headers: await headers(),
      })
      if (!session?.user) {
        throw new Error('User not authenticated')
      }
      return {
        email: session.user.email || '',
        name: session.user.name || ''
      }
    },
  })
}

import { FlowgladServer } from '@flowglad/nextjs/server'
import { createClient } from '@/utils/supabase/server'

export const flowglad = (customerExternalId: string) => {
  return new FlowgladServer({
    customerExternalId,
    getCustomerDetails: async (customerExternalId) => {
      const supabase = await createClient()
      const { data: { user } } = await supabase.auth.getUser()
      if (!user) {
        throw new Error('User not authenticated')
      }
      return {
        email: user.email || '',
        name: user.user_metadata.name || user.email || ''
      }
    },
  })
}

import { FlowgladServer } from '@flowglad/nextjs/server'

export const flowglad = (organizationId: string) => {
  // For B2B apps: organizationId is ID from YOUR app's database
  return new FlowgladServer({
    customerExternalId: organizationId,
    getCustomerDetails: async (customerExternalId) => {
      // Fetch organization details from YOUR database using YOUR org ID
      const org = await db.organizations.findOne({ id: customerExternalId })
      if (!org) {
        throw new Error('Organization not found')
      }
      return {
        email: org.billingEmail || org.ownerEmail,
        name: org.name,
      }
    },
  })
}

Flowglad integrates seamlessly with your auth provider. Read more about auth options here.

3. Create API Route Handler

Create a route handler to handle Flowglad API requests from your frontend. The Server SDK provides route handler constructors that enable your client to communicate with your server, allowing you to load billing and feature access data via the useBilling hook on your frontend. It should handle requests at /api/flowglad/...

Next.js App Router
Next.js Pages Router
Express
Other Frameworks

app/api/flowglad/[...path]/route.ts

import { nextRouteHandler } from '@flowglad/nextjs/server'
import { flowglad } from '@/lib/flowglad'
import { customerIdFromRequest } from '@/lib/auth'

export const { GET, POST } = nextRouteHandler({
  flowglad,
  getCustomerExternalId: async (req) => {
    const externalId = await customerIdFromRequest(req)
    if (!externalId) {
      throw new Error('Unable to determine customer external ID')
    }
    return externalId
  },
})

pages/api/flowglad/[...path].ts

import { pagesRouteHandler } from '@flowglad/nextjs/server'
import { flowglad } from '@/lib/flowglad'
import { customerIdFromRequest } from '@/lib/auth'

export default pagesRouteHandler({
  flowglad,
  getCustomerExternalId: async (req) => {
    const externalId = await customerIdFromRequest(req)
    if (!externalId) {
      throw new Error('Unable to determine customer external ID')
    }
    return externalId
  },
})

server.ts

import express from 'express'
import { expressRouter } from '@flowglad/server/express'
import { flowglad } from './lib/flowglad'
import { customerIdFromRequest } from './lib/auth'

const app = express()

app.use(
  '/api/flowglad',
  expressRouter({
    flowglad,
    getCustomerExternalId: async (req) => {
      const externalId = await customerIdFromRequest(req)
      if (!externalId) {
        throw new Error('Unable to determine customer external ID')
      }
      return externalId
    },
  })
)

server.ts

import { requestHandler } from '@flowglad/server'
import { flowglad } from './lib/flowglad'
import { customerIdFromRequest } from './lib/auth'
import type { HTTPMethod } from '@flowglad/shared'

const flowgladHandler = requestHandler({
  flowglad,
  getCustomerExternalId: async (req) => {
    const externalId = await customerIdFromRequest(req)
    if (!externalId) {
      throw new Error('Unable to determine customer external ID')
    }
    return externalId
  },
})

// Example: Hono, Cloudflare Workers, Elysia, etc.
// Adapt this pattern to your framework
async function handleFlowgladRequest(request: Request): Promise<Response> {
  const url = new URL(request.url)
  const path = url.pathname
    .replace('/api/flowglad/', '')
    .split('/')
    .filter((segment) => segment !== '')

  const result = await flowgladHandler(
    {
      path,
      method: request.method as HTTPMethod,
      query:
        request.method === 'GET'
          ? Object.fromEntries(url.searchParams)
          : undefined,
      body:
        request.method !== 'GET'
          ? await request.json().catch(() => ({}))
          : undefined,
    },
    request
  )

  return Response.json(
    {
      error: result.error,
      data: result.data,
    },
    {
      status: result.status,
    }
  )
}

4. Wrap Your App with FlowgladProvider

Next.js App Router
Next.js Pages Router
Vite + React

app/layout.tsx

import { FlowgladProvider } from '@flowglad/nextjs'

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

pages/_app.tsx

import { FlowgladProvider } from '@flowglad/nextjs'

export default function App({ Component, pageProps }) {
  return (
    <FlowgladProvider>
      <Component {...pageProps} />
    </FlowgladProvider>
  )
}

src/App.tsx

import { FlowgladProvider } from '@flowglad/react'

export default function App({ children }) {
  return (
    <FlowgladProvider>
      {children}
    </FlowgladProvider>
  )
}

5. Use the Billing Hook

Next.js
Vite + React

"use client"

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({
          priceSlug: 'pro_plan',
          successUrl: window.location.href,
          cancelUrl: window.location.href,
          autoRedirect: true,
        })
      }
    >
      Upgrade to Premium
    </button>
  )
}

import { useBilling } from '@flowglad/react'

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({
          priceSlug: 'pro_plan',
          successUrl: window.location.href,
          cancelUrl: window.location.href,
          autoRedirect: true,
        })
      }
    >
      Upgrade to Premium
    </button>
  )
}

Key Features

App Router Support: First-class support for Next.js App Router with Server Components
Pages Router Support: Full compatibility with Pages Router
Type-safe Route Handlers: Automatic type inference for API routes
Server-side Utilities: Access billing data in Server Components and API routes
Client Components: Pre-built components for subscriptions and billing
React Context: Global billing state management

API Reference

Server Exports

Import from @flowglad/nextjs/server:

`FlowgladServer`

The main server class for backend operations. See the Server SDK documentation for full details.

Route Handler

Creates GET and POST handlers for App Router:

import { nextRouteHandler} from '@flowglad/nextjs/server'
import { flowglad } from '@/utils/flowglad'

export const { GET, POST } = nextRouteHandler({
  flowglad,
  // derive customer external id from the request
  getCustomerExternalId: async (req) => {
    // for B2B apps, provide organization or team id instead
    const user = await getUserForReq(req)
    return user.id
  },
  // optional hooks for custom behavior
  beforeRequest: async () => {
    // side effect to run before the request is processed
  },
  afterRequest: async () => {
    // side effect to run after the request is processed
  },
  onError: (error) => {
    // handle errors
  }
})

Client Exports

You can import the following from @flowglad/nextjs:

`FlowgladProvider`

The main provider component. See the React SDK documentation for full details on props and usage.

`useBilling()`

Access billing data and functions. See the React SDK documentation for full API reference.

Server Setup

lib/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,
      }
    },
  })
}

app/api/flowglad/[...path]/route.ts

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
  },
})

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 customerExternalIdFlowglad doesn’t need to know how you authenticate—just provide the ID from your system that represents the customer entity which will be billed.

Complete Example

For full working examples, check out our example projects with authentication and billing integration.

Overview

SDKs

Additional Resources

Overview

Installation

Requirements

Quick Start

1. Set Up Environment Variables

2. Create Server Client

3. Create API Route Handler

4. Wrap Your App with FlowgladProvider

5. Use the Billing Hook

Key Features

API Reference

Server Exports

`FlowgladServer`

Route Handler

Client Exports

`FlowgladProvider`

`useBilling()`

Server Setup

Complete Example

Next Steps

React SDK

Server SDK

​Overview

​Installation

​Requirements

​Quick Start

​1. Set Up Environment Variables

​2. Create Server Client

​3. Create API Route Handler

​4. Wrap Your App with FlowgladProvider

​5. Use the Billing Hook

​Key Features

​API Reference

​Server Exports

​FlowgladServer

​Route Handler

​Client Exports

​FlowgladProvider

​useBilling()

​Server Setup

​Complete Example

​Next Steps

React SDK

Server SDK

Overview

Installation

Requirements

Quick Start

1. Set Up Environment Variables

2. Create Server Client

3. Create API Route Handler

4. Wrap Your App with FlowgladProvider

5. Use the Billing Hook

Key Features

API Reference

Server Exports

`FlowgladServer`

Route Handler

Client Exports

`FlowgladProvider`

`useBilling()`

Server Setup

Complete Example

Next Steps