Skip to main content
This guide will show you how 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, @flowglad/express, 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

​
3. Install Flowglad

bun add @flowglad/nextjs

​
4. 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.
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
Next, set up your Flowglad API route at /api/flowglad/[...path]. Your app will use this to send and receive data from Flowglad.
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
  },
})
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.
You can mount Flowglad’s handler at a different route, but you’ll need to specify it via the serverRoute prop in <FlowgladProvider /> in your React app.

​
5. 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 loadBilling={!!user}>
    { /* ... existing layout JSX ... */}
      {children}
    { /* ... existing layout JSX ... */}
    </FlowgladProvider>
  )
}

​
6. 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>
  }
}

​
7. Join the Community!

Join our Discord

  • Get help fast from the founders and others building in public.

Star on GitHub

  • Support the project and follow our open source roadmap.

Follow us on X

  • Get release updates and feature drops from the founders in real time.