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

# Balances

> Read a customer's credits, current plan, subscriptions and purchases.

A customer's balance is the sum of their unexpired grants from plans and packs, minus what they've spent. [Credits and balances](https://docs.integrateledger.com/concepts/credits.md) explains where grants come from and the order they're spent in.

| You need | Call | Field |
| - | - | - |
| Whether one feature can run now | [`checkCredits`](https://docs.integrateledger.com/getting-started/gating) | `allowed` |
| The balance and current plan | `getCustomer` | `availableCredits`, `currentPlan` |
| What a tracked use left | [`trackUsage`](https://docs.integrateledger.com/getting-started/gating) | `availableCredits` |
| Plan history, renewal controls | `listCustomerSubscriptions` | `items` |
| Packs bought | `listCustomerPurchases` | `items` |

## The customer

```typescript TypeScript theme={"system"}
const customer = await billing.getCustomer({ customerId });
```

```python Python theme={"system"}
customer = billing.get_customer(customer_id=customer_id)
```

```json Response theme={"system"}
{
  "customerId": "user_123",
  "createdAt": "2026-11-07T07:23:35.086Z",
  "availableCredits": 1000,
  "currentPlan": {
    "id": "pro",
    "name": "Pro",
    "status": "active",
    "currentPeriodStart": "2026-11-07T07:25:02.000Z",
    "currentPeriodEnd": "2026-12-07T07:25:02.000Z"
  },
  "overageCapCents": null,
  "overage": null
}
```

* `availableCredits` is the prepaid balance, plan and pack credits together, and never goes below zero.
* `currentPlan` is `null` when the customer has no plan. That isn't a zero balance: they may hold pack credits.
* `currentPlan.status` is `pending_checkout` while a paid plan's Checkout is open; until it's paid, the customer keeps their previous plan's credits.
* `overage` is this period's [overage](https://docs.integrateledger.com/configure-pricing/overage.md), or `null` when the plan has none.

## Subscriptions

`listCustomerSubscriptions` returns each plan the customer has had, newest first. Each has its numeric `id`, `planId`, `status` (see [subscription statuses](https://docs.integrateledger.com/concepts/billing-lifecycle.md#subscription-statuses)), the current period, and a `cancellation` object that drives [renewal controls](https://docs.integrateledger.com/configure-pricing/upgrades-and-downgrades.md#cancel-at-period-end).

## Purchases

`listCustomerPurchases` returns each credit pack the customer has bought, newest first, with its `status` (`pending_checkout` or `paid`) and `creditAmount`. While a purchase is `pending_checkout`, its `creditAmount` is `null` and nothing has been granted.

Both lists return 25 items a page. Pass `limit` (up to 100), and the previous page's `nextCursor` as `cursor`, for more.

## In the dashboard

**Customers** shows each customer's balance as a meter, one segment per grant. **Usage** lists every tracked request, charged or blocked, and opening one shows which grants paid for it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.