Skip to main content
@unitpay/node is the server-side SDK for UnitPay — the billing engine where dollars and credits are both first-class. Use it from your backend to read customers, subscriptions, invoices, payment methods, and credit wallets, track usage, and mint the short-lived portal tokens that power your customer-facing UI.
This SDK authenticates with a secret API key (upay_sk_…). Never ship it to the browser or a client bundle. For customer-facing billing UIs, use @unitpay/react, which consumes the portal tokens you mint here.

​
Installation

npm install @unitpay/node

​
Instantiate

Pass your secret key, or set UNITPAY_API_KEY and let the SDK read it: 
import { UnitPay } from '@unitpay/node';

const unitpay = new UnitPay({ apiKey: process.env.UNITPAY_API_KEY });
new UnitPay() throws if no key is found. Passing a portalToken also throws — those belong in @unitpay/react. The config accepts apiKey, baseUrl, timeout (ms, default 30000), retries (default 2), idempotencyKeyPrefix, and a custom fetch.

​
What it covers

// Usage — track billable events (deducts credits / meters usage)
await unitpay.track({ customerId: 'cus_123', eventName: 'ai-generation', quantity: 1 });

// Customers — read a customer and everything attached to them
await unitpay.customers.get('cus_123');
await unitpay.customers.list();
await unitpay.customers.listInvoices('cus_123');
await unitpay.customers.listPaymentMethods('cus_123');
await unitpay.customers.listCreditAccounts('cus_123'); // credit wallets + balances

// Subscriptions
await unitpay.subscriptions.list({ customerId: 'cus_123' });
await unitpay.subscriptions.cancel('sub_123');
await unitpay.subscriptions.uncancel('sub_123');

// Portal sessions — mint the token @unitpay/react consumes
const { token } = await unitpay.portalSessions.create({ customerId: 'cus_123' });
For high-throughput pipelines, UnitPayIngestion batches and flushes events. The customer-facing UI — subscribe, checkout, gates, and balances — lives in @unitpay/react.

​
Retries, idempotency & typed errors

Every request retries transient failures (429, 409, 5xx, and network errors) with jittered exponential backoff, honoring Retry-After. POST/DELETE requests carry an idempotency key so retries are safe. Failures throw a typed error (AuthenticationError, RateLimitError, ValidationError, …) you can discriminate with instanceof. Verify incoming webhooks with the static UnitPay.verifyWebhook(body, headers, secret).

​
Next steps

Quickstart

Track usage and run credits end to end.

Authentication

Secret keys, and sandbox vs live.

React SDK

Build the customer-facing billing UI.

How it works

The two paths and the two verbs.