---
title: "List wallets"
canonical: "https://bird.com/docs/api/reference/list-billing-wallets"
---

# List wallets

`GET /v1/organization/billing/wallets`

Returns all wallets for the organization. A wallet is created automatically with the organization and pays usage charges. Amounts are decimal strings in `currency_code`; `balance` is the amount currently available to spend, excluding additional `credit_limit` headroom. Requires a delegated user OAuth token with `org:billing:read`; workspace and organization master API keys are refused with `403`.

## Code samples

**TypeScript**

```ts
// Use a delegated user OAuth token with org:billing:read in its issuing region.
const bird = new BirdClient({ apiKey: process.env.BIRD_OAUTH_ACCESS_TOKEN!, region: "eu1" });
await bird.billingWallets.list();
```

Examples: [TypeScript](/docs/api/reference/list-billing-wallets.ts.md) · [Python](/docs/api/reference/list-billing-wallets.py.md) · [Go](/docs/api/reference/list-billing-wallets.go.md) · [PHP](/docs/api/reference/list-billing-wallets.php.md) · [cURL](/docs/api/reference/list-billing-wallets.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "id": "wal_01krdgeqcxet5s7t44vh8rt9mg",
      "currency_code": "USD",
      "balance": "118.00",
      "settled_balance": "150.00",
      "renewal_reserved": "25.00",
      "renewal_required": "30.00",
      "collection_status": "none",
      "collection_renewal": "30.004",
      "collection_required": "42.00",
      "collection_usage_buffer": "10.00",
      "collection_deficit": "2.00",
      "credit_limit": "0.00"
    }
  ]
}
```

## Response body

- `data` (array of object, required)
- `data.id` (string, required)
- `data.currency_code` (string, required): ISO 4217 currency code.
- `data.balance` (string, required): Balance you can spend, in currency units. Usage is charged as it happens, so this drops within seconds of sending and can be lower than the balance the wallet transactions add up to, which only reflects charges that have settled. Funds held for upcoming renewals are also excluded. Credit headroom is reported separately in `credit_limit`, and postpaid accounts can keep spending past a zero balance up to that limit.
- `data.settled_balance` (string, required): Settled wallet balance in currency units, before active reservations are deducted.
- `data.renewal_reserved` (string, required): Amount currently held for prepared subscription renewals and scheduled plan changes, in currency units.
- `data.renewal_required` (string, required): Total amount required for prepared subscription renewals and scheduled plan changes, including tax, in currency units.
- `data.collection_status` (string, required)

  Automatic collection state:
  - `none`: No retained collection run.
  - `in_progress`: Collection is active, though payment may still require customer action.
  - `exhausted`: Automatic retries have stopped and customer action is needed.

  Possible values: `none`, `in_progress`, `exhausted`
- `data.collection_renewal` (string, required): Part of collection_required needed for unfunded renewal fees, in exact currency units.
- `data.collection_required` (string, required): Total wallet funding still required by the current automatic collection run, in exact currency units.
- `data.collection_usage_buffer` (string, required): Part of collection_required needed for the configured auto-topup amount, in currency units.
- `data.collection_deficit` (string, required): Part of collection_required needed to cover the wallet shortfall after reservations and approved credit, in currency units.
- `data.credit_limit` (string, required): Credit limit in currency units. `0.00` for prepaid wallets.
- `data.provisional` (boolean, required): When `true`, the wallet currency has not yet been committed and can be changed once. When `false`, the currency is permanent.
- `data.created_at` (string, required)
- `data.updated_at` (string, required)

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)