---
title: "List wallets"
method: GET
path: "/v1/organization/billing/wallets"
tags: ["billing"]
---

# List wallets

`GET /v1/organization/billing/wallets`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/organization/billing/wallets`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

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

## Headers

- `X-Organization-Id` string

## Response `200`

The wallets.

- BillingWalletList
  - `data` BillingWallet[], required
    - `id` string, required
    - `currency_code` string, required: ISO 4217 three-letter currency code.
    - `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.
    - `settled_balance` string, required: Settled wallet balance in currency units, before active reservations are deducted.
    - `renewal_reserved` string, required: Amount currently held for prepared subscription renewals and scheduled plan changes, in currency units.
    - `renewal_required` string, required: Total amount required for prepared subscription renewals and scheduled plan changes, including tax, in currency units.
    - `collection_status` 'none' | 'in_progress' | 'exhausted', 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.
    - `collection_renewal` string, required: Part of collection_required needed for unfunded renewal fees, in exact currency units.
    - `collection_required` string, required: Total wallet funding still required by the current automatic collection run, in exact currency units.
    - `collection_usage_buffer` string, required: Part of collection_required needed for the configured auto-topup amount, in currency units.
    - `collection_deficit` string, required: Part of collection_required needed to cover the wallet shortfall after reservations and approved credit, in currency units.
    - `credit_limit` string, required: Credit limit in currency units. `0.00` for prepaid wallets.
    - `provisional` boolean, required: When `true`, the wallet currency has not yet been committed and can be changed once. When `false`, the currency is permanent.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error

## Changes

- **2026-10-20** `a1977645a499`: 1 info
  - endpoint added
- **2026-10-20** `6cec81ac4862`: 1 breaking
  - api path removed without deprecation
- **2026-10-20** `3e2a50466454`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/messagebird/apis/bird-api/changes/v1/organization/billing/wallets/get.md)

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/483bb7bfdc89?raw)