---
title: "Get the prepaid balance"
method: GET
path: "/balance"
tags: ["Billing"]
---

# Get the prepaid balance

`GET /balance`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/balance`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `project:read`)

A live project pays in advance: you top up a balance in the portal (https://app.hypamoon.com/balance) and every SMS, call minute and number is deducted from it immediately. This returns the balance, what was spent this calendar month against the spending cap, the automatic top-up settings and the latest 20 transactions, newest first. All amounts are in euro, excluding VAT. Read-only: topping up and the automatic top-up settings are in the portal. With a test key you see the balance of the live project with test: true. Test mode is free, except AI above the free daily test budget (chat replies, agent model calls), which is deducted from this balance.

## Response `200`

The balance with the latest transactions.

- Balance: The prepaid balance with the latest transactions.
  - `balance_eur` number, required: The prepaid balance in euro, excluding VAT. Can be slightly below zero after a call that ran on.
  - `currency` 'EUR', required: Always EUR.
  - `spent_this_month_eur` number, required: What was deducted this calendar month (minus refunds). Counts toward the spending cap.
  - `spend_cap_eur` number, nullable, required: The spending cap per calendar month, or null without one.
  - `auto_reload` AutoReload, required: Automatic top-up with a saved card.
    - `enabled` boolean, required: Whether automatic top-up is switched on. Change it in the portal.
    - `active` boolean, required: Whether it can run now: switched on, with a saved card that has not expired.
    - `threshold_eur` number, required: When the balance drops below this amount, a top-up starts.
    - `amount_eur` number, required: How much each automatic top-up adds, excluding VAT.
    - `max_per_month` integer, required: The most automatic top-ups per calendar month.
    - `used_this_month` integer, required: How many automatic top-ups ran this calendar month.
    - `disabled_reason` string, nullable, required: Why it is off or cannot run: no_card, card_expired, repeated_failures or turned_off. Null when it is active.
    - `card` object, nullable, required: The saved card used for automatic top-up, or null without one.
      - `brand` string, nullable, required: The card brand, like Visa or Mastercard.
      - `last4` string, nullable, required: The last four digits.
      - `expiry` string, nullable, required: The expiry date of the card.
  - `transactions` Transaction[], required: The latest 20 transactions, newest first.
    - `id` string, required: The id of the transaction.
    - `type` 'top_up' | 'charge' | 'refund' | 'adjustment', required: top_up: money added with a payment. charge: usage deducted. refund: a charge given back (an SMS the carrier refused, for example). adjustment: a correction by Hypamoon support.
    - `source` 'payment' | 'sms' | 'call' | 'number' | 'chat' | 'site' | 'support', required: What caused it: a payment, an SMS, a call, a number, a chat reply of the assistant, site requests above what the plan includes, or Hypamoon support.
    - `amount_eur` number, required: The amount in euro excluding VAT, with a sign: positive for a top-up or refund, negative for a charge. Up to four decimals.
    - `balance_after_eur` number, required: The balance right after this transaction, in euro excluding VAT.
    - `description` string, required: What it was for, in a few words.
    - `quantity` number, nullable, required: How many units, like 2 SMS segments or 3 minutes. Null for a top-up.
    - `unit` string, nullable, required: The unit of quantity, like segment, minute or month. Null for a top-up.
    - `reference_id` string, nullable, required: The id of what caused it: a message, a call, a number or a payment.
    - `created_at` string, date-time, required: When the transaction was booked.
  - `test` boolean, required: true with a test key: you see the balance of the live project, read-only. Test mode is free and never touches the balance.

## Other responses

- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required.
- `404`: Not Found: not_found.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

[API](https://skmtc.dev/hypamoon/apis/hypamoon-api.md) · [All operations](https://skmtc.dev/hypamoon/apis/hypamoon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hypamoon/apis/hypamoon-api/revisions/9f0b90004c06?raw)