# Read billing

URL: https://heaven.dev/docs/reference/billing/view
Updated: 2026-11-21

Read billing status and prepaid balance for the selected account.

`GET /v1/organization/billing/`

## Parameters

- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.

## Returns

- `data` (object, always present): The account's billing state, wallet and purchases.
  - `auto_topup_cents` (integer): Automatic top-up amount in cents. May be omitted.
  - `auto_topup_monthly_limit_cents` (integer, always present): Monthly automatic top-up ceiling, in cents.
  - `balance_micros` (integer, always present): Total remaining wallet credit, in millionths of a dollar.
  - `can_manage` (boolean, always present): Whether you can manage this account's billing.
  - `card` (object): Saved payment card. May be omitted.
    - `brand` (string): Card brand reported by the payment provider. May be omitted.
    - `exp_month` (integer): Expiration month, from 1 through 12. May be omitted.
    - `exp_year` (integer): Four-digit expiration year. May be omitted.
    - `last4` (string, always present): Last four digits of the card number.
  - `card_form` (boolean): Whether the card setup form is available. May be omitted.
  - `card_saved` (boolean, always present): Whether a payment card is saved.
  - `contacts` (string[]): Additional recipients of billing email. May be omitted.
  - `egress` (object): This month's outbound traffic usage, charges and cap. May be omitted.
    - `allowance_bytes` (integer, always present): Internet egress included for the month, in bytes.
    - `cap` (string, always present): Egress cap setting: `default`, `amount` or `off`.
    - `cap_micros` (integer): Monthly cap in millionths of a dollar. Absent when the cap is off. May be omitted.
    - `charged_micros` (integer, always present): Egress charged so far this month, in millionths of a dollar.
    - `charging` (boolean, always present): Whether egress overage is currently billed.
    - `month` (string (date-time), always present): Month being measured.
    - `not_charged_bytes` (integer): Overage bytes not charged while the wallet was past its grace period. May be omitted.
    - `over_bytes` (integer, always present): Usage above the included allowance, in bytes.
    - `projected_bytes` (integer, always present): Estimated monthly egress based on use so far, in bytes.
    - `slowed` (boolean, always present): Whether the account's internet egress is currently slowed because of its egress cap, its spending cap or its wallet state.
    - `used_bytes` (integer, always present): Internet egress used this month, in bytes.
    - `would_charge_micros` (integer): What overage would cost if charging were enabled, in millionths of a dollar. May be omitted.
  - `entries` (object[] | null, always present): Recent wallet ledger entries.
    - `items` (object): One wallet ledger entry.
      - `amount_micros` (integer, always present): Signed change in wallet balance, in millionths of a dollar.
      - `at` (string (date-time), always present): When the entry was recorded.
      - `kind` (string, always present): Reason for the credit or debit.
      - `pool` (string): Pool associated with the entry, when present. May be omitted.
  - `held` (boolean): Whether billing has placed the account on hold. May be omitted.
  - `lasts_hours` (number): Estimated wallet lifetime in hours at current spending. May be omitted.
  - `next_renewal` (string (date-time)): When the next monthly renewal is due. May be omitted.
  - `notices` (string[] | null, always present): Billing issues or changes needing attention.
  - `paid_micros` (integer, always present): Remaining purchased wallet credit, in millionths of a dollar.
  - `pay_by` (string): Account's payment method. May be omitted.
  - `payments_off` (boolean): Whether payments are disabled. May be omitted.
  - `per_hour_micros` (integer, always present): Hourly wallet spending, in millionths of a dollar.
  - `promo_expiring` (object[]): Promotional credits expiring soon. May be omitted.
    - `items` (object): A wallet credit grant.
      - `amount_micros` (integer, always present): Original credit amount in millionths of a dollar.
      - `created_at` (string (date-time), always present): When the credit was granted.
      - `expires_at` (string (date-time)): When unused credit expires, if an expiry is set. May be omitted.
      - `id` (string, always present): Credit grant's ID.
      - `refundable` (boolean, always present): Whether this credit is eligible for a refund.
      - `remaining_micros` (integer, always present): Credit still available, in millionths of a dollar.
      - `scope` (string[]): Spending categories this credit can pay for. May be omitted.
      - `source` (string, always present): Origin of this credit.
  - `promo_micros` (integer, always present): Remaining promotional wallet credit, in millionths of a dollar.
  - `purchases` (object[] | null, always present): Purchases being billed and any scheduled changes.
    - `items` (object): A billed capacity purchase and its pending changes.
      - `amount_micros` (integer, always present): Price per billing period, in millionths of a dollar.
      - `change` (string): Scheduled change to this purchase. May be omitted.
      - `change_at` (string (date-time)): When the scheduled change takes effect. May be omitted.
      - `change_plan` (integer): Plan selected by a scheduled resize. May be omitted.
      - `id` (string, always present): Capacity purchase ID.
      - `model` (string, always present): Billing model.
      - `pending` (boolean): Whether the first payment is pending. May be omitted.
      - `plan` (integer, always present): Purchased plan number.
      - `pools` (string[] | null, always present): Pools that can use capacity from this purchase.
      - `region` (string): Purchase's region. May be omitted.
      - `switch_saves_micros` (integer): Estimated monthly savings from switching to monthly billing, in millionths of a dollar. May be omitted.
  - `renewal_micros` (integer, always present): Account's monthly renewal total, in millionths of a dollar.
  - `spend_alert_micros` (integer | null, always present): Monthly spending alert threshold in millionths of a dollar; null disables alerts.
  - `spending_cap_micros` (integer | null, always present): Monthly spending cap in millionths of a dollar, past which nothing is charged; null for none.
  - `subscription_status` (string): Payment provider's current subscription state. May be omitted.
  - `time_zone` (string, always present): Account's time zone for billing communications.
  - `usage_emails` (boolean, always present): Whether monthly usage emails are enabled.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- API key permission: `billing view`.

## Examples

```sh tab="heaven CLI"
heaven billing view
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev billing view
  [--organization ORGANIZATION]
```

```sh tab="cURL"
curl https://heaven.dev/v1/organization/billing/ \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

```json tab="MCP"
{ "tool": "billing_view",
  "arguments": {  } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "auto_topup_monthly_limit_cents": 50000,
    "balance_micros": 1010000000,
    "can_manage": true,
    "card_saved": false,
    "egress": {
      "allowance_bytes": 242000000000,
      "cap": "default",
      "cap_micros": 30000080,
      "charged_micros": 0,
      "charging": true,
      "month": "2026-11-01T00:00:00Z",
      "over_bytes": 0,
      "projected_bytes": 0,
      "slowed": false,
      "used_bytes": 0
    },
    "entries": [
      {
        "amount_micros": 1000000000,
        "at": "2026-11-16T12:00:00Z",
        "kind": "credit"
      },
      {
        "amount_micros": 10000000,
        "at": "2026-11-16T12:00:00Z",
        "kind": "credit"
      }
    ],
    "lasts_hours": 24576.601129063656,
    "notices": [],
    "paid_micros": 0,
    "payments_off": true,
    "per_hour_micros": 41096,
    "promo_micros": 1010000000,
    "purchases": [
      {
        "amount_micros": 41096,
        "id": "cap-49dc0f5161fd4e9b",
        "model": "hourly",
        "plan": 1,
        "pools": [
          "web"
        ],
        "switch_saves_micros": 10000080
      }
    ],
    "renewal_micros": 0,
    "spend_alert_micros": null,
    "spending_cap_micros": null,
    "time_zone": "UTC",
    "usage_emails": true
  }
}
```
