Skip to main content

​
Install the packages

npm install @billingos/sdk @tanstack/react-query
PackageWhere it runsPurpose
@billingos/sdkBrowser (React)UI components, hooks, client
@tanstack/react-queryBrowser (React)Data fetching and caching (peer dependency)
For server-side operations (session tokens, entitlements), install the Node SDK separately: 
npm install @billingos/node

​
Peer dependencies

The React SDK requires these peer dependencies: 
{
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0",
  "@tanstack/react-query": "^5.0.0"
}
Most React projects already have react and react-dom. You just need to add @tanstack/react-query if you don’t have it already.

​
Requirements

  • React 18.0 or later (React 19 supported)
  • Node.js 18.0 or later (for the server SDK)

​
Environment variables

Add your BillingOS secret key to your server environment:
.env.local
BILLINGOS_SECRET_KEY=sk_test_your_secret_key_here
Your secret key starts with sk_test_ (sandbox) or sk_live_ (production). Never expose it in client-side code.
You can find your API keys in the BillingOS Dashboard.

​
Next step

Set up the BillingOSProvider to connect the SDK to your app.