> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useunitpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> The @unitpay/node server SDK — customers, subscriptions, usage, and portal sessions.

`@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.

<Warning>
  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`](/react/introduction), which consumes the portal tokens you mint here.
</Warning>

## Installation

```bash theme={null}
npm install @unitpay/node
```

## Instantiate

Pass your secret key, or set `UNITPAY_API_KEY` and let the SDK read it:

```ts theme={null}
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

```ts theme={null}
// 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`](/react/introduction).

## 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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/documentation/getting-started/setup">
    Track usage and run credits end to end.
  </Card>

  <Card title="Authentication" icon="key" href="/documentation/authentication">
    Secret keys, and sandbox vs live.
  </Card>

  <Card title="React SDK" icon="react" href="/react/introduction">
    Build the customer-facing billing UI.
  </Card>

  <Card title="How it works" icon="diagram-project" href="/documentation/how-it-works">
    The two paths and the two verbs.
  </Card>
</CardGroup>