Billing

What your organization has, what it owes, and what it bought. Reads only.

Billing is admin-only: the token owner must currently be an organization Admin (403 insufficient_scope otherwise). Payments, payment methods, credit purchases and billing-mode changes are handled in the portal.

Credit amounts are integer nano-USD (*_nanousd, 10⁻⁹ USD — exact), with a convenience *_usd number alongside; invoices carry integer cents in their own currency. Balances and invoices are views of the same record as Usage; if an API response and an issued invoice ever disagree, the invoice governs.

Python examples share this setup:

import os
import requests

BASE = "https://portal.<domain>/api/v1/mgmt"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['TF_PAT']}"

Retrieve the balance

GET /api/v1/mgmt/billing/balance

The organization's prepaid credit wallet — the balance every inference request is checked against.

curl https://portal.<domain>/api/v1/mgmt/billing/balance \
  -H "Authorization: Bearer $TF_PAT"

balance = s.get(f"{BASE}/billing/balance", timeout=30).json()
print(balance["available_nanousd"] / 1e9, balance["currency"])

{
  "available_nanousd": 1835617883000,
  "available_usd": 1835.617883,
  "currency": "USD",
  "wallet_present": true
}

If billing data is temporarily unavailable the call is 502 upstream_unavailable — retry.

List credit grants

GET /api/v1/mgmt/billing/grants

Every credit movement on the organization — grants, top-ups, refunds — newest first. Paginated.

curl https://portal.<domain>/api/v1/mgmt/billing/grants \
  -H "Authorization: Bearer $TF_PAT"

grants = s.get(f"{BASE}/billing/grants", timeout=30).json()["data"]
granted = sum(g["amount_nanousd"] for g in grants)
print(f"net credit added: ${granted / 1e9:,.2f}")

{
  "data": [
    {
      "id": "grant_9f2c41d07a5b3e18",
      "created_at": "2026-09-01T12:00:00Z",
      "source": "stripe",
      "memo": "Credit top-up",
      "amount_nanousd": 2000000000000,
      "amount_usd": 2000,
      "reference": "pi_3P…"
    },
    {
      "id": "grant_1ab07c3de4f59260",
      "created_at": "2026-03-02T09:41:17Z",
      "source": "signup",
      "memo": "Starter credit",
      "amount_nanousd": 25000000000,
      "amount_usd": 25,
      "reference": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

List invoices

GET /api/v1/mgmt/billing/invoices

Paginated, newest first.

curl https://portal.<domain>/api/v1/mgmt/billing/invoices \
  -H "Authorization: Bearer $TF_PAT"

invoices = s.get(f"{BASE}/billing/invoices", timeout=30).json()["data"]
open_invoices = [i for i in invoices if i["status"] == "open"]

{
  "data": [
    {
      "id": "f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f",
      "stripe_invoice_id": "in_1Q…",
      "amount_cents": 421193,
      "currency": "usd",
      "status": "paid",
      "period_start": "2026-08-01T00:00:00Z",
      "period_end": "2026-09-01T00:00:00Z",
      "pdf_url": "https://…/invoice.pdf",
      "created_at": "2026-09-01T02:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve an invoice

GET /api/v1/mgmt/billing/invoices/{id}

Returns one invoice — the same object as a list row. An id that is not one of your organization's invoices returns 404.

curl https://portal.<domain>/api/v1/mgmt/billing/invoices/f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f \
  -H "Authorization: Bearer $TF_PAT"

invoice = s.get(f"{BASE}/billing/invoices/{invoice_id}", timeout=30).json()
if invoice["pdf_url"]:
    pdf = requests.get(invoice["pdf_url"], timeout=60)

Reconcile usage with billing

1. Pull the period from GET /usage with from/to set to the invoice's period_start/period_end.
2. When the invoice's currency is usd, compare the usage totals.cost_nanousd with the invoice's amount_cents directly (1 cent = 10,000,000 nano-USD).
3. Between invoices, watch GET /billing/balance fall as usage accrues.

Both sides are the same record, so this is a check, not a fix-up — if they disagree, contact support. Quote the X-Request-Id of both responses.

Errors specific to billing