Installation

Install the packages

npm install @billingos/sdk @tanstack/react-query

pnpm add @billingos/sdk @tanstack/react-query

yarn add @billingos/sdk @tanstack/react-query

Package	Where it runs	Purpose
`@billingos/sdk`	Browser (React)	UI components, hooks, client
`@tanstack/react-query`	Browser (React)	Data fetching and caching (peer dependency)

For server-side operations (session tokens, entitlements), install the Node SDK separately:

npm install @billingos/node

pnpm add @billingos/node

yarn add @billingos/node

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.

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.

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