Node SDK overview - BillingOS

What is the Node SDK?

The @billingos/node package runs on your server. Use it to:

Create session tokens — authenticate your users with BillingOS
Check entitlements — verify feature access in API routes
Track usage — record metered usage from your backend
Manage customers — create and update customer records
Manage subscriptions — create, cancel, and modify subscriptions

Installation

npm install @billingos/node

pnpm add @billingos/node

yarn add @billingos/node

Initialize

import { BillingOS } from "@billingos/node";

const billing = new BillingOS({
  secretKey: process.env.BILLINGOS_SECRET_KEY!,
});

Configuration

Option	Type	Default	Description
`secretKey`	`string`	Required	Your BillingOS secret key
`apiUrl`	`string`	Auto-detected	API base URL override
`timeout`	`number`	`30000`	Request timeout in ms
`maxRetries`	`number`	`3`	Max retry attempts for failed requests

Auto-environment detection

The SDK automatically detects your environment from the key prefix:

Key prefix	Environment	API URL
`sk_test_*`	Sandbox	`https://sandbox-api.billingos.dev`
`sk_live_*`	Production	`https://api.billingos.dev`

You can override this with the apiUrl option or the BILLINGOS_API_URL environment variable.

Quick examples

Create a session token

const { sessionToken, expiresAt } = await billing.createSessionToken({
  externalUserId: "user_123",
  expiresIn: 3600,
});

Check a feature entitlement

const result = await billing.checkEntitlement("user_123", "api_calls");

if (result.has_access) {
  // Allow the operation
} else {
  // Return 403
}

Track usage

await billing.trackUsage({
  customerId: "user_123",
  featureKey: "api_calls",
  quantity: 1,
});

Error handling

import { BillingOS, ValidationError, NotFoundError } from "@billingos/node";

try {
  await billing.createSessionToken({ externalUserId: "" });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error("Invalid input:", error.message);
  } else if (error instanceof NotFoundError) {
    console.error("Resource not found:", error.message);
  }
}

Error class	Status	Description
`ValidationError`	400	Input validation failed
`AuthenticationError`	401	Invalid API key
`AuthorizationError`	403	Insufficient permissions
`NotFoundError`	404	Resource not found
`RateLimitError`	429	Rate limit exceeded
`ServerError`	500+	Server-side error
`NetworkError`	—	Connection/timeout error

​What is the Node SDK?

​Installation

​Initialize

​Configuration

​Auto-environment detection

​Quick examples

​Create a session token

​Check a feature entitlement

​Track usage

​Error handling