Skip to main content
@unitpay/react gives your app type-safe React hooks and components for building customer-facing billing UIs on UnitPay — the billing engine where dollars and credits are both first-class. One provider exposes a customer’s subscriptions, invoices, payment methods, credit wallets, entitlements, and checkout.

​
How hooks work

Every hook is built on TanStack Query and reads from a single shared cache scoped to the current customer:
  • Auth is a short-lived portal-session token (portalToken) minted on your server with @unitpay/node. The SDK attaches it as a bearer token and refreshes it for you — proactively (~60s before it expires) and reactively (on a 401). No secret keys ever reach the browser.
  • One fetch, many gates. useCustomer() loads the customer and their entitlements once; useEntitlement and the <FeatureGate> components then resolve from that cache. Pass requestedUsage (or { fresh: true }) when you need a live server check.
  • Mutations (useTopUp, useChangePlan, …) resolve to a SettleOutcome describing how money moved, and auto-invalidate the affected queries. See Settlement model.

​
Dollars and credits

Both billing paths are modeled side by side — subscriptions and invoices on the dollar side; wallets, grants, and the ledger on the credit side. Credit affordances render on every relevant surface regardless of whether the current plan uses credits.

​
Installation

npm install @unitpay/react react @tanstack/react-query
react (>=18) and @tanstack/react-query (^5) are peer dependencies — install one copy in your app so the SDK shares your QueryClient.

​
Next steps

UnitPayProvider

Wrap your app and configure the SDK.

useCustomer

The customer’s state and core billing actions.

Entitlement gates

Declarative access control components.

Next.js adapter

Proxy requests through your own backend.