Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.billingos.dev/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through adding BillingOS to your app. By the end, you’ll have a working pricing page with checkout.
Prerequisites: A BillingOS account with at least one product created in the dashboard.

​
Step 1: Install the packages

npm install @billingos/sdk @tanstack/react-query
For your server, install the Node SDK separately: 
npm install @billingos/node

​
Step 2: Create a session token endpoint

BillingOS uses session tokens to securely identify your customers. You create the token on your server (so your secret key stays private), and the SDK uses it automatically for all API calls. Add your secret key to your environment:
.env.local
BILLINGOS_SECRET_KEY=sk_test_your_secret_key_here
Then create an endpoint that generates a token for the logged-in user: 
import { BillingOS } from "@billingos/node";

const billing = new BillingOS({
  secretKey: process.env.BILLINGOS_SECRET_KEY!,
});

export async function GET(request: Request) {
  // Replace with your actual auth — NextAuth, Clerk, Supabase, etc.
  const userId = await getLoggedInUserId(request);

  const { sessionToken, expiresAt } = await billing.createSessionToken({
    externalUserId: userId, // your user's ID from your database
    expiresIn: 3600,        // 1 hour
  });

  return Response.json({ sessionToken, expiresAt });
}
The externalUserId is your user’s ID from your own database. BillingOS uses it to link the session to the right customer’s subscriptions and entitlements.

​
Step 3: Add the provider

BillingOSProvider wraps your app and handles fetching the session token automatically.
app/providers.tsx
"use client";

import { BillingOSProvider } from "@billingos/sdk";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <BillingOSProvider sessionTokenUrl="/api/billingos-session">
      {children}
    </BillingOSProvider>
  );
}
app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
That’s all the setup. The SDK now:
  • Fetches a session token from your endpoint when the app loads
  • Attaches the token to every API call
  • Refreshes the token automatically before it expires
  • Injects required CSS on mount (no separate CSS import needed)
Next.js App Router requires "use client" for components that use React context. That’s why we create a separate Providers wrapper — your layout stays a Server Component.

​
Step 4: Add a pricing page

Drop in the PricingTable component. It fetches your products and renders a complete pricing page with built-in checkout.
app/pricing/page.tsx
import { PricingTable } from "@billingos/sdk";

export default function PricingPage() {
  return (
    <div className="max-w-5xl mx-auto py-16 px-4">
      <PricingTable />
    </div>
  );
}
When a customer selects a plan, the checkout modal opens automatically — no extra code needed. PricingTable component

​
Step 5: Test it

Start your dev server and visit /pricing: 
npm run dev
You should see your products displayed as pricing cards. Click any plan to open the checkout modal.
Test card number: Use 4242 4242 4242 4242 with any future expiry date and any CVC.

​
What’s next?

Show a pricing page

Customize your pricing table with filters, themes, and custom actions.

Manage subscriptions

Add a self-service customer portal.

Gate features

Control access to features based on plan.