> ## 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.
# BillingOSProvider
> The provider component that connects the SDK to your app.
## 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
```tsx app/layout.tsx theme={null}
import { Providers } from "./providers";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
## Props
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.**
A session token string for manual mode. You're responsible for refreshing the token yourself. **Use this or `sessionTokenUrl` — one is required.**
Options for token fetching behavior (automatic mode only).
How often to refresh the token (ms).
Refresh when the browser tab gains focus.
Override the customer ID.
Customer's email address.
Customer's display name.
Your BillingOS organization ID.
Customize the visual appearance of BillingOS components. See [Appearance](#appearance) below.
Content to render while the session token is being fetched.
SDK client configuration.
Custom API URL (auto-detected from token by default).
Request timeout in ms (default: 30000).
Custom headers for API requests.
Custom TanStack Query client. If omitted, the SDK creates one internally.
Enable debug logging.
Your app content.
## Automatic vs manual tokens
### Automatic (recommended)
```tsx theme={null}
```
The SDK calls your endpoint, stores the token, and refreshes it before expiry. Zero maintenance.
### Manual
```tsx theme={null}
```
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:
```tsx theme={null}
{children}
```
### 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:
```tsx theme={null}
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 |