---
title: "Get Billing Status"
method: GET
path: "/billing/billing-status"
tags: ["billing"]
---

# Get Billing Status

`GET /billing/billing-status`

Get billing status for the authenticated user.

Returns:
    - The authoritative spendable credit balance and admission result
    - Whether user has a payment method on file
    - Stripe customer ID
    - List of payment methods

## Response `200`

Successful Response

- BillingStatusResponse — Response model for billing status.
  - `team_id` string, nullable
  - `has_payment_method` boolean, required
  - `card_verified` boolean
  - `stripe_customer_id` string, nullable
  - `payment_methods` PaymentMethodInfo[]
    - `id` string, required
    - `type` string
    - `brand` string, required
    - `last4` string, required
    - `exp_month` integer, nullable
    - `exp_year` integer, nullable
    - `billing_name` string, nullable
    - `billing_address` BillingAddress — Billing address on file for a payment method, as held by Stripe. All fields are optional because Stripe only returns the components the customer provided. The UI renders this read-only; it is never edited in Pioneer (changes are made in the Stripe customer portal).
      - `line1` string, nullable
      - `line2` string, nullable
      - `city` string, nullable
      - `state` string, nullable
      - `postal_code` string, nullable
      - `country` string, nullable
  - `billing_activated` boolean — Authoritative inference-admission result computed by the server. Frontend refusal surfaces must consume this field rather than re-deriving it from payment or balance details.
  - `spendable_credit_balance` number — Authoritative wallet balance the inference gate will honour, in credits. Frontend balance surfaces MUST consume this field so the display matches the wallet the request path spends.
  - `exact_credit_balance` string, nullable — The team's exact ledger balance — the most recent monthly snapshot plus every entry since it — in dollars, not credits. ``Decimal``, not ``float``, matching the ledger EDD's invariant 8 ('Money is Decimal end to end... No float on any path that touches a balance') and the sibling ``LedgerBalanceResponse.total`` this value is sourced from (``billing/ledger/balance.py::read_exact_balance``). This is the EDD's 'display, disputes, and reconciliation' number, distinct from ``spendable_credit_balance`` on purpose: that field mirrors the aggregator cache admission reads, which can lag a real top-up or debit by up to one fold cycle (ENG-7048). Frontend balance surfaces that render a dollar figure to the user MUST prefer this field; surfaces that decide whether a spend would be admitted (the zero-balance CTA, funding gates) MUST keep reading ``spendable_credit_balance`` so the decision never disagrees with the gate. ``None`` only when the caller has no active team.
  - `overdraft_available` boolean — Whether the admission gate will still serve this team with the visible balance at or below zero, because auto-refill is on and the overdraft floor has headroom left. Surfaces exist to stop the UI announcing 'out of funds' during the seconds between the balance reaching zero and the refill landing, which invites a second manual payment for a top-up already being collected. Computed server-side from the same ``headroom_to_floor`` the request path reads, so the copy cannot drift from the gate.

## Changes

- **2026-09-24** `1cffaad2a921` — 4 breaking, 5 warning, 3 info
  - removed the required property `credit_limit` from the response with the `200` status
  - removed the required property `exceeds_free_tier` from the response with the `200` status
  - removed the required property `free_tier_remaining` from the response with the `200` status
  - removed the required property `total_usage` from the response with the `200` status
  - …8 more
- **2026-08-05** `31dfe831e079` — 1 info
  - added the optional property `current_period_start` to the response with the `200` status

[Change history](https://skmtc.dev/pioneer/apis/brain-api/changes/billing/billing-status/get.md)

---

[API](https://skmtc.dev/pioneer/apis/brain-api.md) · [All operations](https://skmtc.dev/pioneer/apis/brain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pioneer/apis/brain-api/revisions/1cffaad2a921?raw)