---
title: "Billing summary"
method: GET
path: "/v2/billing/summary"
tags: ["billing"]
---

# Billing summary

`GET /v2/billing/summary`

## Request

- Base URL: `https://api.stuut.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stuut.ai/v2/billing/summary`
- Auth: HTTP bearer

Return balances and the current-period draft invoice.

## Query parameters

- `force_refresh` boolean

## Response `200`

Successful Response

- BillingSummary: Current balances, spend, and draft invoice.
  - `tier` 'payg' | 'postpaid' | 'enterprise' | 'legacy', required: Stuut-owned commercial policy; only PAYG is balance-gated.
  - `pools` CommitPool[], required: Every ACTIVE funding instrument (open access window), balances included.
    - `id` string, required: Instrument id — stable across refreshes.
    - `name` string, nullable, required: Display label, e.g. 'Signup credit' or 'Dunning package'.
    - `type` 'PREPAID' | 'POSTPAID' | 'CREDIT', required: PREPAID = purchased top-up; POSTPAID = minimum commitment, never spendable; CREDIT = free money (trial, promo, allotment).
    - `active` string, decimal, required: Amount granted in the currently-active access window, in dollars — what `consumed` + `balance` measure against (a multi-window commit shows THIS window, not the lifetime total).
    - `balance` string, decimal, required: Remaining in dollars — never negative (Metronome clamps at 0; the overdraw lives on the draft invoice as `uncovered_total`).
    - `expires_at` string, date-time, nullable, required: When the active window's balance expires; null = perpetual.
    - `consumed` string, decimal, required: Spent from the active window (active - balance), floored at 0.
  - `upcoming_invoice` UpcomingInvoice, required: The active contract's current-period draft invoice.
    - `total` string, decimal, required: Projected invoice total in dollars, PRE-TAX.
    - `start_timestamp` string, date-time, nullable, required: Billing period start.
    - `end_timestamp` string, date-time, nullable, required: Billing period end — when the draft issues.
    - `lines` InvoiceLine[], required: Every line: usage, scheduled fees, credit applications.
      - `key` 'active_accounts' | 'collections' | 'cash_application' | 'deductions' | 'disputes' | 'voice' | 'sms', required: Stable slug for a product offered by Stuut.
      - `name` string, required: The line label as it will appear on the invoice.
      - `type` 'USAGE' | 'SCHEDULED' | 'CREDIT', required: USAGE = metered consumption; SCHEDULED = a fixed/recurring fee; CREDIT = a credit/commit application (negative).
      - `quantity` string, decimal, nullable, required: Metered quantity (a COUNT, not money); null for non-metered lines.
      - `unit_price` string, decimal, nullable, required: Price per unit in dollars; null for non-metered lines.
      - `total` string, decimal, required: Line total in dollars; negative = credit applied.
      - `applied_commit_or_credit` AppliedCommitOrCredit, required: The funding instrument a credit-application line drew from.
        - `id` string, required: Instrument id — matches `pools[].id`.
        - `type` 'PREPAID' | 'POSTPAID' | 'CREDIT', required: Instrument type.
      - `sub_line_items` SubLineItem[], nullable, required: Per-tier / per-charge breakdown of this line, when Metronome provides one.
        - `name` string, required: Sub-line label, e.g. a tier band.
        - `quantity` string, decimal, required: Quantity within this sub-line.
        - `price` string, decimal, nullable, required: Price per unit in dollars, when priced.
        - `subtotal` string, decimal, required: Sub-line subtotal in dollars.
  - `spend` string, decimal, required: GROSS spend this period — every metered (USAGE) line summed, BEFORE any credit/commit coverage; consumption regardless of who pays. Scheduled fees excluded.
  - `uncovered_total` string, decimal, required: Usage net of applied credits (USAGE + CREDIT lines summed; scheduled fees excluded) — ~$0 while funds cover everything, the uncovered remainder once they run out.
  - `balances` Balances, required: Funding totals grouped by active pool type.
    - `prepaid` TypeBalance, required: Aggregate across the active pools of one type.
      - `active` string, decimal, required: Σ pool.active — total granted (a commit's minimum-spend target for postpaid).
      - `consumed` string, decimal, required: Σ consumed across the type's active pools.
      - `balance` string, decimal, required: Remaining: active - consumed.
    - `postpaid` TypeBalance, required: Aggregate across the active pools of one type.
      - `active` string, decimal, required: Σ pool.active — total granted (a commit's minimum-spend target for postpaid).
      - `consumed` string, decimal, required: Σ consumed across the type's active pools.
      - `balance` string, decimal, required: Remaining: active - consumed.
    - `credit` TypeBalance, required: Aggregate across the active pools of one type.
      - `active` string, decimal, required: Σ pool.active — total granted (a commit's minimum-spend target for postpaid).
      - `consumed` string, decimal, required: Σ consumed across the type's active pools.
      - `balance` string, decimal, required: Remaining: active - consumed.
  - `net_balance` string, decimal, required: The spendable position. `balances.prepaid.balance` while there's one; once that's exhausted (PAYG only), the overdraw as a NEGATIVE amount — Metronome clamps instrument balances at 0, so uncovered usage exists only on the draft (`uncovered_total`, negated here so overdrawn reads below zero).

## Other responses

- `422`: Validation Error

---

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