BillingOSProvider

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

Create a session token endpoint

Create a providers file

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

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.

string

A session token string for manual mode. You’re responsible for refreshing the token yourself. Use this or sessionTokenUrl — one is required.

object

Options for token fetching behavior (automatic mode only).

Show child attributes

number

How often to refresh the token (ms).

boolean

Refresh when the browser tab gains focus.

string

Override the customer ID.

string

Customer’s email address.

string

Customer’s display name.

string

Your BillingOS organization ID.

AppearanceConfig

Customize the visual appearance of BillingOS components. See Appearance below.

ReactNode

Content to render while the session token is being fetched.

BillingOSClientOptions

SDK client configuration.

Show child attributes

string

Custom API URL (auto-detected from token by default).

number

Request timeout in ms (default: 30000).

Record<string, string>

Custom headers for API requests.

QueryClient

Custom TanStack Query client. If omitted, the SDK creates one internally.

boolean

default:"false"

Enable debug logging.

ReactNode

required

Your app content.

Automatic vs manual tokens

Automatic (recommended)

<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

Property	Type	Description
`theme`	`"light" \| "dark" \| "auto"`	Color scheme. `auto` follows the user’s system preference.
`light`	`AppearanceVariables`	Variable overrides for light theme.
`dark`	`AppearanceVariables`	Variable overrides for dark theme.

AppearanceVariables

Variable	Type	Description
`colorPrimary`	`string`	Primary accent color (buttons, links, highlights).
`colorBackground`	`string`	Background color for components.
`colorText`	`string`	Text color.
`borderRadius`	`string`	Border radius for cards, buttons, inputs.
`fontFamily`	`string`	Font 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

Value	Type	Description
`client`	`BillingOSClient \| null`	The SDK client instance (null before token loads)
`apiUrl`	`string`	Resolved API URL
`appUrl`	`string`	Resolved app URL
`customerId`	`string \| undefined`	Current customer’s ID
`customerEmail`	`string \| undefined`	Customer’s email
`customerName`	`string \| undefined`	Customer’s name
`organizationId`	`string \| undefined`	Organization ID
`appearance`	`AppearanceConfig \| undefined`	Appearance configuration
`debug`	`boolean`	Debug mode

Getting Started

Components

Hooks

Advanced

Overview

Basic setup

Props

Automatic vs manual tokens

Automatic (recommended)

Manual

Appearance

AppearanceConfig

AppearanceVariables

Accessing the context

Context values

​Overview

​Basic setup

​Props

​Automatic vs manual tokens

​Automatic (recommended)

​Manual

​Appearance

​AppearanceConfig

​AppearanceVariables

​Accessing the context

​Context values

Overview

Basic setup

Props

Automatic vs manual tokens

Automatic (recommended)

Manual

Appearance

AppearanceConfig

AppearanceVariables

Accessing the context

Context values