Skip to main content

​
Overview

The BillingOSClient class provides direct access to all BillingOS API methods. Use it when you need more control than hooks and components provide.
Most apps should use the hooks and components instead. The client is for advanced use cases like custom data fetching, server-side rendering, or non-React integrations.

​
Access the client

From within a BillingOSProvider: 
import { useBillingOS } from "@billingos/sdk";

function MyComponent() {
  const { client } = useBillingOS();

  // client is null until the session token loads
  if (!client) return null;

  const subscription = await client.getSubscription("sub_123");
}
Or create a standalone client: 
import { BillingOSClient } from "@billingos/sdk";

const client = new BillingOSClient("bos_session_test_xxx", {
  baseUrl: "https://api.billingos.dev",
});

​
Constructor options

interface BillingOSClientOptions {
  baseUrl?: string                     // API base URL (auto-detected from token)
  environment?: "production" | "sandbox"
  version?: string                     // API version
  headers?: Record<string, string>     // Custom headers
  timeout?: number                     // Request timeout (ms)
}

​
Methods

​
Customers

MethodDescription
createCustomer(input)Create a new customer
getCustomer(id)Get a customer by ID
listCustomers(params?)List customers (paginated)
updateCustomer(id, input)Update customer details
deleteCustomer(id)Delete a customer

​
Subscriptions

MethodDescription
createSubscription(input)Create a subscription
getSubscription(id)Get a subscription
listSubscriptions(params?)List subscriptions (paginated)
updateSubscription(id, input)Update a subscription
cancelSubscription(id, immediately?)Cancel a subscription
reactivateSubscription(id)Reactivate a cancelled subscription
previewSubscription(id, input)Preview subscription update proration
getAvailablePlans(subscriptionId)Get upgrade/downgrade options
previewPlanChange(subId, input)Preview plan change cost
changePlan(subId, input)Execute a plan change

​
Entitlements and features

MethodDescription
checkEntitlement(input)Check if a customer has access to a feature
listEntitlements(customerId?)List all entitlements

​
Usage tracking

MethodDescription
trackUsage(event)Track a usage event
getUsageMetrics(customerId?, featureKey?)Get usage metrics

​
Invoices

MethodDescription
getInvoice(id)Get an invoice
listInvoices(params?)List invoices (paginated)

​
Payment methods

MethodDescription
listPaymentMethods(customerId)List payment methods
removePaymentMethod(id)Remove a payment method
setDefaultPaymentMethod(id)Set the default payment method

​
Checkout

MethodDescription
createCheckout(input)Create a checkout session
confirmCheckout(clientSecret, paymentMethodId)Confirm a payment

​
Checkout modal (iframe)

Access via client.checkout.*:
MethodDescription
checkout.createSession(input)Create a checkout session for the modal
checkout.getSession(sessionId)Get session details
checkout.confirmPayment(secret, pmId)Confirm payment

​
Portal (iframe)

Access via client.portal.*:
MethodDescription
portal.createSession(input?)Create a portal session
portal.getSessionStatus(sessionId)Check session validity
portal.getPortalData(sessionId)Get aggregated portal data

​
Pricing

MethodDescription
getProducts(planIds?)Fetch products for pricing table

​
Upgrade nudge

MethodDescription
checkUsage()Check if an upgrade nudge should be shown

​
Error classes

The client throws typed errors you can catch: 
import {
  BillingOSError,
  UnauthorizedError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  ServerError,
  NetworkError,
} from "@billingos/sdk";

try {
  await client.getSubscription("sub_invalid");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log("Subscription not found");
  } else if (error instanceof UnauthorizedError) {
    console.log("Session token expired");
  }
}

​
Imperative checkout API

Open checkout from anywhere in your app — even outside React components: 
// Via the global window object
window.billingOS?.checkout.open({
  priceId: "price_pro_monthly",
  onSuccess: (subscription) => console.log("Subscribed!", subscription),
  onError: (error) => console.error("Failed:", error),
  onCancel: () => console.log("Cancelled"),
});

// Or using the exported function
import { openCheckout } from "@billingos/sdk";

const result = await openCheckout({
  priceId: "price_pro_monthly",
  sessionToken: "bos_session_test_...",
});