Quickstart

Process your first payment in 3 minutes

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.

Integrate by Prompt (recommended)

Flowglad has an MCP server! It can give your AI coding agents more context with the Flowglad docs. You can add it to your AI coding tool of choice by following the MCP server documentation.

1. Install The Flowglad Package

bun

bun add @flowglad/nextjs

2. Codebase Overview

Flowglad can create a custom integration prompt for each pricing model in your organization.

If you haven’t already, you’ll need to complete a codebase overview to give Flowglad context about your codebase. You’ll be asked to complete this overview when creating a new organization or you can do it later in settings.

Simply copy the overview prompt into your AI coding tool of choice and paste the output into the provided text area in Flowglad.

3. One Shot Integration

To access a pricing model’s custom integration prompt, go to your pricing model, click “More Options”, click “Integrate”, and you’ll see the prompt (it may take some time to generate).

You can then copy this prompt into your AI coding tool and it should be able to one shot the integration.

Continue Manually

1. Install Flowglad

Next.js

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.

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

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

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.

Supabase Auth

// 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.

Next

'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.