Skip to main content

​
Overview

BillingOSProvider is a React context provider that initializes the BillingOS SDK client and makes it available to all child components and hooks. You must wrap your app with this provider before using any BillingOS components or hooks.

​
Basic setup

1

Create a session token endpoint

2

Create a providers file

3

Wrap your layout

app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

​
Props

​
sessionTokenUrl
string
URL to fetch session tokens from your server. The SDK calls this endpoint automatically, stores the token, and refreshes it before expiry. Use this or sessionToken — one is required.
​
sessionToken
string
A session token string for manual mode. You’re responsible for refreshing the token yourself. Use this or sessionTokenUrl — one is required.
​
sessionTokenOptions
object
Options for token fetching behavior (automatic mode only).
​
customerId
string
Override the customer ID.
​
customerEmail
string
Customer’s email address.
​
customerName
string
Customer’s display name.
​
organizationId
string
Your BillingOS organization ID.
​
appearance
AppearanceConfig
Customize the visual appearance of BillingOS components. See Appearance below.
​
loadingFallback
ReactNode
Content to render while the session token is being fetched.
​
options
BillingOSClientOptions
SDK client configuration.
​
queryClient
QueryClient
Custom TanStack Query client. If omitted, the SDK creates one internally.
​
debug
boolean
default:"false"
Enable debug logging.
​
children
ReactNode
required
Your app content.

​
Automatic vs manual tokens

<BillingOSProvider sessionTokenUrl="/api/billingos-session">
The SDK calls your endpoint, stores the token, and refreshes it before expiry. Zero maintenance.

​
Manual

<BillingOSProvider sessionToken={myToken}>
You manage token fetching and refresh yourself. Useful if you have a custom auth setup.

​
Appearance

Customize the visual appearance of all BillingOS components through the appearance prop: 
<BillingOSProvider
  sessionTokenUrl="/api/billingos-session"
  appearance={{
    theme: "auto", // "light" | "dark" | "auto"
    light: {
      colorPrimary: "#16A34A",
      colorBackground: "#FFFFFF",
      colorText: "#1A1A1A",
      borderRadius: "8px",
      fontFamily: "Inter, sans-serif",
    },
    dark: {
      colorPrimary: "#22C55E",
      colorBackground: "#0A0A0A",
      colorText: "#FAFAFA",
      borderRadius: "8px",
      fontFamily: "Inter, sans-serif",
    },
  }}
>
  {children}
</BillingOSProvider>

​
AppearanceConfig

PropertyTypeDescription
theme"light" | "dark" | "auto"Color scheme. auto follows the user’s system preference.
lightAppearanceVariablesVariable overrides for light theme.
darkAppearanceVariablesVariable overrides for dark theme.

​
AppearanceVariables

VariableTypeDescription
colorPrimarystringPrimary accent color (buttons, links, highlights).
colorBackgroundstringBackground color for components.
colorTextstringText color.
borderRadiusstringBorder radius for cards, buttons, inputs.
fontFamilystringFont family for all text.
The SDK injects CSS on mount automatically — no separate CSS import needed.

​
Accessing the context

Use the useBillingOS hook to access the SDK client from any component: 
import { useBillingOS } from "@billingos/sdk";

function MyComponent() {
  const { client, customerId, appearance } = useBillingOS();

  // Use client for custom API calls
  const products = await client?.getProducts();
}

​
Context values

ValueTypeDescription
clientBillingOSClient | nullThe SDK client instance (null before token loads)
apiUrlstringResolved API URL
appUrlstringResolved app URL
customerIdstring | undefinedCurrent customer’s ID
customerEmailstring | undefinedCustomer’s email
customerNamestring | undefinedCustomer’s name
organizationIdstring | undefinedOrganization ID
appearanceAppearanceConfig | undefinedAppearance configuration
debugbooleanDebug mode