Quickstart

Set up Lumen in 5 minutes.

You'll:

• Connect Stripe to Lumen
• Create a plan in Lumen
• Drop a Pricing Table into your app
• Test a checkout with Stripe test cards

Create accounts and connect Stripe

1. Get your Stripe API Keys

Already have Stripe? Perfect! Test mode API keys are all you need - you don't need business verification in Stripe for testing Lumen.

1. In Stripe dashboard, make sure you are in test mode OR using a sandbox - there will be a bar at the top of the screen telling you this.
2. Go to the search box at the top, search for "api keys" and click on Developers > API Keys
3. Here, you will see your test mode secret key and publishable keys. These will be needed in the next step.

2. Create your Lumen account

We'll create a test account on Lumen to safely test billing with fake payments.

Go to getlumen.dev/login and create your test account using email signup (not Google login).

Email options:

• Gmail / Google Workspace users: Add +lumen_test to your email (e.g., yourname+lumen_test@gmail.com)
• Other users: Use any secondary email address

Choose any password for your test account and create your account.

Go through the onboarding. Select Stripe as your payment provider. Put your test mode Stripe API keys when asked. In the merchant details, you can fill out your real details or test data. Select USD as your currency for now.

Create your first Plan

After the onboarding, you'll land on the Plans → Create page. Let's create a test plan:

• Name: Premium Plan
• Monthly Price: 10. Next, toggle on yearly price
• Yearly Price: 8

We'll add two features to this plan (by clicking on the Add New Feature button):

1. A boolean feature (it allows a simple yes / no check - does the customer have access to this feature or not?)
2. A usage based feature with credits and overage billing. We offer 500 API calls per month and any usage above that is charged at $0.05 per API call

Set environment variables

Add your Lumen secret key and publishable key in your Next JS app (not using Next JS? That's ok - see the setup page for details).

You should have gotten these during onboarding. If you didn't save these keys, you'll need to create a new secret key the getlumen.dev/developer/apikeys page.

LUMEN_API_KEY=sk_live_...                    # Secret key for backend operations
NEXT_PUBLIC_LUMEN_PUBLISHABLE_KEY=pk_live_... # Publishable key for frontend components

Integrate the PricingTable component

Installation

First, install the required packages:

# Server package
npm install @getlumen/server

# Our shadcn components for the PricingTable and the CustomerPortal
# You can customize them manually or for eg, with Cursor
npx shadcn@latest add https://getlumen.dev/pricing-table.json

You can see a demo of how the PricingTable will look like on your website by going to getlumen.dev/pricingtable. Here's an example of a typical setup - a free plan, a paid plan and an enterprise plan:

Frontend Integration

Import the PricingTable component and add it to your pricing page:

import { PricingTable } from "@/components/ui/pricing-table";
import { authClient } from "@/lib/auth-client" // use your auth lib. we're using better-auth in this example

export default function PricingPage() {
  // get auth details from your auth provider
  const { data: session } = authClient.useSession();

  return (
    <PricingTable
      lumenPublishableKey={process.env.NEXT_PUBLIC_LUMEN_PUBLISHABLE_KEY}
      userId={session?.user?.id} // <- change this according to your auth provider
      loginRedirectUrl="/login"
    />
  );
}

Props:

• lumenPublishableKey: Your Lumen publishable key from the environment variables
• userId: The ID of the currently logged-in user
• loginRedirectUrl: Clicking subscribe will redirect to this url if userId is null / undefined

To use the more features of the PricingTable, you can look at this help page.

Implement feature access in your backend

To control access to features and track usage, use the server-side functions provided by @getlumen/server:

import { sendEvent, isFeatureEntitled } from "@getlumen/server";
import { authClient } from "@/lib/auth-client" // use your auth lib. we're using better-auth in this example

export async function POST(request: NextRequest) {
  const { data: session } = authClient.useSession();

  if (
    // Check if user still has credits remaining
    await isFeatureEntitled({
      feature: "api-calls",
      userId: session?.user?.id,
    })
  ) {
    // Do backend logic here ... for eg, process an API call
    const result = await processApiCall();

    // after completion you need torecord usage with:
    sendEvent({
      name: "api-calls",
      userId: session?.user?.id,
    });
  }
}

If you want to use feature gates on the frontend, you will need some additional setup. Follow the instructions on the Setup page. Once you have the full setup, you can read this guide on how to use feature gates.

Test your checkout flow

Run your app locally, login to your app and open the pricing page. Start the flow and use this Stripe test card:

• Card number: 4242 4242 4242 4242
• Any future expiry, any CVC (for eg, 04/44 and 444)

You should see a successful subscription in Lumen on the subscriptions page.

Done!

Lumen billing is ready, you can test all the flows now. When you're ready to go live, you can create a new Lumen account using your live mode API keys. Everything else will work the same!