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

# Customers & subscriptions

> Read customers, their invoices, payment methods, credit wallets, and subscriptions.

Read-side access to who you bill and what they owe. List methods return a [`PagePromise`](/node/errors) you can `await` for one page or `for await` to auto-paginate.

<Note>
  Credits are first-class: every customer can hold one or more credit wallets alongside their dollar balances. `listCreditAccounts` returns them.
</Note>

## unitpay.customers.get

Fetch one customer by ID. Returns `Promise<Customer>` (`id`, `email`, `name`, `status`, `type`, `salesMotion`, address fields, `metadata`, …).

```ts theme={null}
const customer = await unitpay.customers.get('cus_123');
```

## unitpay.customers.list

List customers. Takes optional query `params` (`Record<string, unknown>`); returns `PagePromise<Customer>`.

```ts theme={null}
// One page
const { data, hasMore, nextCursor } = await unitpay.customers.list();

// Auto-paginate every customer
for await (const customer of unitpay.customers.list()) {
  console.log(customer.id);
}
```

## unitpay.customers.listInvoices

Invoices for a customer. Returns `PagePromise<Invoice>` (`totalAmount`, `amountDue`, `amountPaid`, `currency`, `status`, `dueDate`, `paidAt`, …).

```ts theme={null}
for await (const invoice of unitpay.customers.listInvoices('cus_123')) {
  console.log(invoice.invoiceNumber, invoice.status, invoice.amountDue);
}
```

## unitpay.customers.listPaymentMethods

Payment methods on file. Returns `PagePromise<PaymentMethod>` (`type`, `status`, `isDefault`, and `card: { brand, last4, expMonth, expYear }`).

```ts theme={null}
const { data } = await unitpay.customers.listPaymentMethods('cus_123');
```

## unitpay.customers.listCreditAccounts

The customer's credit wallets. Returns `PagePromise<CreditAccount>` — one per credit currency, with `balance`, `available`, `reserved`, and `currencyId`.

```ts theme={null}
for await (const wallet of unitpay.customers.listCreditAccounts('cus_123')) {
  console.log(wallet.currencyId, wallet.available, 'of', wallet.balance);
}
```

## unitpay.subscriptions.list

List subscriptions. Filter with query `params` — `{ customerId, status }`. This is also how you list one customer's subscriptions (there's no customer-nested route). Returns `PagePromise<Subscription>` (`planId`, `status`, `billingInterval`, `collectionMethod`, `currentBillingPeriodEnd`, …).

```ts theme={null}
const { data } = await unitpay.subscriptions.list({
  customerId: 'cus_123',
  status: 'active',
});
```

## unitpay.subscriptions.cancel

Cancel a subscription by ID. Optional `params` (`Record<string, unknown>`) controls cancellation behavior (e.g. immediate vs. at period end). Returns `Promise<Subscription>`.

```ts theme={null}
const sub = await unitpay.subscriptions.cancel('sub_123');
```

## unitpay.subscriptions.uncancel

Reverse a pending cancellation before it takes effect. Returns `Promise<Subscription>`.

```ts theme={null}
const sub = await unitpay.subscriptions.uncancel('sub_123');
```

## See also

<CardGroup cols={2}>
  <Card title="Usage & ingestion" icon="gauge" href="/node/usage">
    Track billable events.
  </Card>

  <Card title="Portal sessions" icon="id-card" href="/node/portal-sessions">
    Mint the token for customer-facing UI.
  </Card>
</CardGroup>