> ## Documentation Index
> Fetch the complete documentation index at: https://partner-docs.contro.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Balance

> Monitor your prefunded partner balance

The Contro Partner API uses a prefunded model - your partner account holds a balance that is debited when cards are used. Monitor your balance and review transactions to track fund movement.

## Check balance

Retrieve your current balance:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.contro.me/v1/partner/balance \
    -H "x-contro-api-key: $CONTRO_API_KEY"
  ```

  ```typescript SDK (Node) theme={null}
  const balance = await contro.balance.retrieve();
  console.log(`${balance.balance} ${balance.currency}`);
  ```

  ```python SDK (Python) theme={null}
  balance = contro.balance.retrieve()
  print(f"{balance.balance} {balance.currency}")
  ```

  ```typescript TypeScript (fetch) theme={null}
  const balance = await fetch(`${BASE_URL}/partner/balance`, {
    headers,
  }).then((r) => r.json());

  console.log(`${balance.balance} ${balance.currency}`);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "balance": 50000.00,
  "currency": "USD"
}
```

| Field | Type | Description |
| - | - | - |
| `balance` | number | Current balance amount in the account's currency. Example: `50000.00` |
| `currency` | string | ISO 4217 currency code. Example: `"USD"` |

## Balance transactions

View the history of credits and debits on your balance:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.contro.me/v1/partner/balance/transactions?limit=20" \
    -H "x-contro-api-key: $CONTRO_API_KEY"
  ```

  ```typescript SDK (Node) theme={null}
  const txns = await contro.balance.listTransactions({ limit: 20 });
  ```

  ```python SDK (Python) theme={null}
  txns = contro.balance.list_transactions(limit=20)
  ```

  ```typescript TypeScript (fetch) theme={null}
  const txns = await fetch(
    `${BASE_URL}/partner/balance/transactions?limit=20`,
    { headers }
  ).then((r) => r.json());
  ```
</CodeGroup>

### Query parameters

| Parameter | Type | Description |
| - | - | - |
| `page` | integer | Page number (default `1`). |
| `limit` | integer | Items per page (1–100, default `20`). |
| `status` | string | Filter by transaction status. One of `pending`, `action_required`, `accepted`, `rejected`, `failed`, `void`. |
| `type` | string | Filter by transaction type (e.g. `card_issuance`, `card_funding`, `kyc`). |
| `from` | string | ISO 8601 start timestamp (inclusive). |
| `to` | string | ISO 8601 end timestamp (inclusive). |

### Response

```json theme={null}
{
  "data": [
    {
      "id": "btx_abc123",
      "amount": -42.50,
      "type": "card_debit",
      "status": "completed",
      "description": "Card transaction - Coffee Shop",
      "ref": "tx_def456",
      "timestamp": "2026-03-20T14:30:00Z",
      "createdAt": "2026-03-20T14:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}
```

### Balance transaction fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Balance transaction ID. Example: `"btx_abc123"` |
| `amount` | number | Amount in the account's currency. Positive = credit, negative = debit. Example: `-42.50` |
| `type` | string | Transaction type. One of `card_debit`, `card_refund`, `top_up`, `fee` |
| `status` | string | Transaction status. One of `pending`, `completed`, `failed` |
| `description` | string \| null | Human-readable description, or `null`. Example: `"Card transaction - Coffee Shop"` |
| `ref` | string \| null | ID of the related card transaction or top-up, or `null`. Example: `"tx_def456"` |
| `timestamp` | string | ISO 8601 timestamp of when the transaction occurred. Example: `"2026-03-20T14:30:00Z"` |
| `createdAt` | string | ISO 8601 timestamp of when the record was created. Example: `"2026-03-20T14:30:00Z"` |

### Transaction types

| Type | Description |
| - | - |
| `card_debit` | Debit from a card transaction |
| `card_refund` | Refund credited back |
| `top_up` | Manual balance top-up |
| `fee` | Platform or service fee |

## Low balance alerts

Configure [webhooks](/partner/webhooks) to receive notifications when your balance falls below a threshold, so you can top up before card transactions are declined.

## Balance thresholds

Your account can have up to three balance thresholds, configured with Contro during onboarding. They are evaluated after every settlement and balance change, and each level acts exactly once per downward crossing — re-arming when your balance recovers above the threshold.

| Threshold | What happens when your balance crosses below it |
| - | - |
| **Alert** | A [`balance.alert`](/partner/webhooks/balance-alert) webhook fires immediately so you can top up. |
| **Block issuance** | New card issuance is rejected with an `ISSUANCE_BLOCKED` error while the balance stays at or below this level. Existing cards keep working. The block lifts automatically once you top up above the threshold. |
| **Freeze** | Spending is stopped at the freeze threshold. For cards on a program with real-time authorization, transactions are **declined in real time** while your balance stays at or below the threshold and **resume automatically** once you top up above it — no manual unfreeze. For cards on programs without real-time authorization, all active cards are frozen and are **not** unfrozen automatically — after topping up, unfreeze them via `POST /partner/cards/{id}/unfreeze` or contact support. |

Settlements can take your balance negative (spend that was already authorized is still honored); thresholds exist so you can act before that happens. The sandbox evaluates the same thresholds against your sandbox balance, so you can rehearse the alert and recovery flow with [`simulate-transaction`](/partner/sandbox#simulate-transaction) and [`reset-balance`](/partner/sandbox#reset-balance).