Skip to main content
This guide will show you how to set up Flowglad in your app. It’s optimized for Next.js, but it can be adapted for any React + Node.js application.
Looking for detailed SDK documentation? Check out our SDK documentation for comprehensive guides on @flowglad/nextjs, @flowglad/react, and more.

​
1. Sign Up For Flowglad

Create a Flowglad account.

​
2. Add Your API Key

Add your Flowglad API key to your environment
.env
FLOWGLAD_SECRET_KEY="sk_test_...."
Quicklinks to add your key to your secrets: Vercel Dashboard Infisical Dashboard

​
Installation & Setup

From here you can install and setup Flowglad in one of two ways.

​
1. Install Flowglad

bun add @flowglad/nextjs

​
2. Server Setup

First, set up a Flowglad server factory function. Do this in a file that can be imported wherever you need to access billing data, or make calls to Flowglad.
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,
      }
    },
  })
}
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
Next, set up your Flowglad API route at /api/flowglad/[...path]. Your app will use this to send and receive data from Flowglad.
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
  },
})
The getCustomerExternalId function extracts the customer ID from your app’s database (via your authentication system). Flowglad doesn’t care how you authenticate—just return the ID from your system that represents the billing entity (user ID for B2C, organization ID for B2B). This is not Flowglad’s customer ID.
Flowglad integrates seamlessly with your auth provider. Read more about auth options here.
You can mount Flowglad’s handler at a different route, but you’ll need to specify it via the baseURL prop in <FlowgladProvider /> in your React app. Flowglad will automatically append /api/flowglad to the baseURL when making requests.

​
3. Set up React

Next, you need to set up the FlowgladProvider component.
// app/layout.tsx
import { PropsWithChildren } from 'react'
import { FlowgladProvider } from '@flowglad/react'
// or wherever you initialize your supabase client
import { createClient } from '@/utils/supabase'

export default function RootLayout({
  children,
}: PropsWithChildren) {
    const supabase = createClient();
  const {
    data: { user }
  } = await supabase.auth.getUser();
  return (
    <FlowgladProvider>
    { /* ... existing layout JSX ... */}
      {children}
    { /* ... existing layout JSX ... */}
    </FlowgladProvider>
  )
}

​
4. useBilling

Use the useBilling hook to get billing data on your customer’s frontend.
'use client'
import { useBilling } from '@flowglad/nextjs'

export default function Billing() {
  const { checkFeatureAccess } = useBilling()
  if (!checkFeatureAccess) {
    return <div>Loading ...</div>  
  }
  if (checkFeatureAccess("my_feature")) {
    return <div>You have access!</div>
  } else {
    return <div>Please upgrade</div>
  }
}
Not using the SDKs? Check out our guide for integrating with HTTP.