Skip to main content

​
What’s in the SDK

The @billingos/sdk package gives you everything you need to add billing to a React app:
CategoryWhat you get
ComponentsDrop-in UI for pricing, checkout, portals, feature gates
HooksTanStack Query-powered hooks for subscriptions, entitlements, usage
ClientLow-level API client for custom integrations
ProviderContext provider that manages auth and SDK state

​
Components

ComponentPurpose
<PricingTable />Display plans with pricing, features, and built-in checkout
<CheckoutModal />Secure, iframe-based checkout modal
<CustomerPortal />Self-service subscription, invoices, and payment management
<FeatureGate />Show/hide content based on plan entitlements
<UsageDisplay />Progress bars showing feature usage vs limits
<UpgradeNudge />Automated upgrade prompts when users hit limits
<UpgradePrompt />Manual upgrade call-to-action

​
Hooks

HookPurpose
useSubscriptionFetch and manage subscriptions
useCheckoutProgrammatic checkout flow
useFeatureCheck feature access and track usage
useEntitlementsList entitlements and check limits
useTrackUsageTrack usage events and view metrics
useProductsFetch products and pricing

​
What you don’t need to do

  • No Stripe SDK — BillingOS handles all Stripe communication. No @stripe/stripe-js or @stripe/react-stripe-js needed.
  • No PCI compliance — Checkout runs in a secure iframe. Card data never touches your servers.
  • No webhook handling — Entitlements update automatically after checkout.

​
Quick example

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

function App() {
  return (
    <BillingOSProvider sessionTokenUrl="/api/billingos-session">
      <PricingTable />
    </BillingOSProvider>
  );
}
That’s a complete pricing page with checkout in 7 lines.

​
Architecture

BillingOSProvider (manages auth + SDK client)
  └── Components (PricingTable, CheckoutModal, CustomerPortal, etc.)
        └── Hooks (useSubscription, useFeature, useCheckout, etc.)
              └── BillingOSClient (API layer)

​
Requirements

  • React 18+ (React 19 supported)
  • TypeScript types included — no separate @types package needed
  • Built on TanStack Query for data fetching and caching
  • Tree-shakeable bundle (sideEffects: false)

​
Next steps

Installation

Install the SDK and set up peer dependencies.

BillingOSProvider

Configure the provider and connect to your app.