---
title: "Retrieve your prepaid balance"
method: GET
path: "/billing/balance"
tags: ["Billing"]
---

# Retrieve your prepaid balance

`GET /billing/balance`

## Request

- Base URL: `https://developers.ozav.io/v2`
- URL: `https://developers.ozav.io/v2/billing/balance`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Your organization's prepaid credit, the one each paid call on OZAV Services is charged to
before it runs. Read it to stop before a call is refused with `402 INSUFFICIENT_CREDIT`.

`billing_mode: postpaid` has no balance (`balance: null`): its calls are billed on the
monthly statement (`GET /statements`). The credit belongs to the organization, so a test key
reads the same balance; calls made with a test key are never charged.

## Response `200`

The balance.

- BillingBalance
  - `object` 'billing_balance', required
  - `billing_mode` 'prepaid' | 'postpaid', required
  - `balance` object, nullable, required: The prepaid credit. `null` for a postpaid organization.
    - `amount` string, required: Decimal string.
    - `currency` 'USD', required
  - `as_of` string, date-time, required

## Other responses

- `401`: Missing or invalid API key.
- `403`: The organization lacks the entitlement (code ENTITLEMENT_REQUIRED) or the key lacks the scope (code INSUFFICIENT_SCOPE). On money-moving requests (POST /transfers, POST /wallets/{wallet_id}/transfers) a compliance hold on the customer answers with code COMPLIANCE_HOLD: the hold is reviewed and lifted on OZAV's side; retrying does not clear it. When the only hold is a pause until pending onboarding documents are received, a withdrawal answers CUSTOMER_DOCUMENTS_PENDING instead: send what `requirements` on GET /customers/{id} lists; OZAV lifts the pause after reviewing it. On OZAV Services (live without the platform's KYB), any API outside decisions, screenings, lists and self-custody wallets answers with code PRODUCTION_NOT_ACTIVATED.
- `503`: A dependency OZAV needs (storage, a resource lookup) could not be reached, so OZAV fails closed rather than guess. Safe to retry with the same `Idempotency-Key` where the operation accepts one.

---

[API](https://skmtc.dev/ozav/apis/ozav-api.md) - [All operations](https://skmtc.dev/ozav/apis/ozav-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ozav/apis/ozav-api/revisions/4133dc2109d7?raw)