Get balance

GET /v1/balance returns a snapshot of the caller's account balance. The balance is the running total of all ledger activity (payment credits, invoice debits, refunds, and administrative adjustments) and is what pay-from-balance draws against.

All monetary amounts are expressed in micro-USD: 1 USD = 1_000_000 micro. The server is authoritative — do no client-side arithmetic to reconstruct the balance; read amount_micro directly. For a live-updating value (pushed on every credit and debit), subscribe to the balance event stream instead of polling this endpoint.

New users with no ledger history are not an error: the endpoint returns 200 OK with amount_micro: 0 and locked: false rather than 404, so the response shape is always consistent.

When locked is true, the balance has been administratively frozen and locked_at carries the freeze time. While frozen, pay-from-balance attempts fail with balance_locked (see Notes).

This endpoint takes no path, query, or body parameters. Authentication is carried entirely by the session cookie established at sign-in.

When the balance is frozen, locked is true and locked_at is present:

{
  "amount_micro": 12500000,
  "locked": true,
  "locked_at": 1748534400,
  "updated_at": 1748534400
}

A brand-new user with no ledger history:

{
  "amount_micro": 0,
  "locked": false,
  "updated_at": 1748534400
}

Errors use the shared envelope { "error": "<message>" }. See errors.md for the full envelope and handling guidance.

JavaScript (fetch)

const res = await fetch("https://api.triport.io/v1/balance", {
  headers: { "Content-Type": "application/json" },
  credentials: "include", // send the session cookie
});
if (!res.ok) {
  const { error } = await res.json().catch(() => ({}));
  throw new Error(error ?? `HTTP ${res.status}`);
}
const balance = await res.json();
const usd = balance.amount_micro / 1_000_000;
console.log(`Balance: $${usd.toFixed(2)}`, balance.locked ? "(frozen)" : "");

TypeScript SDK (@triport/sdk)

import { TriportClient } from "@triport/sdk";


const client = new TriportClient(); // uses the session cookie


const balance = await client.balance.get();
//    ^? { amount_micro: number; locked: boolean; updated_at: number; locked_at?: number }


const usd = balance.amount_micro / 1_000_000;
console.log(`Balance: $${usd.toFixed(2)}`);

Python (triport-sdk)

from triport import TriportClient


client = TriportClient()  # uses the session cookie


balance = client.balance.get()
usd = balance["amount_micro"] / 1_000_000
print(f"Balance: ${usd:.2f}", "(frozen)" if balance["locked"] else "")

• Micro-USD everywhere. amount_micro is an integer in millionths of a dollar. Divide by 1_000_000 for display; never store a rounded float as the source of truth.
• Lock semantics. locked: true with locked_at set means the balance is frozen. While frozen, pay-from-balance fails with the balance_locked error — surface the freeze state in the UI before letting a user attempt to pay from balance.
• No 404 for new users. Accounts without ledger history return zeros, so you can render a balance widget without special-casing "not found".
• Live updates. This endpoint is a point-in-time snapshot. For a value that stays current, use the balance event stream, which emits a snapshot baseline on every (re)connect followed by balance_credit / balance_debit frames.
• Ledger detail. To list the individual credits and debits behind the balance, use list ledger entries.