---
title: "Get the workspace billing summary"
method: GET
path: "/v1/billing"
tags: ["billing"]
---

# Get the workspace billing summary

`GET /v1/billing`

## Request

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

The caller's subscription tier/status, seats, remaining credits, and the Stripe publishable key.

## Headers

- `X-Tenant-Id` string, nullable

## Response `200`

Successful Response

- BillingSummary: GET /v1/billing: the tenant's current plan, credit balance, and publishable key.
  - `tier` 'free' | 'founding' | 'team' | 'business' | 'enterprise' | 'custom', required: The subscription tier (price anchor + included-credit allowance). ``FOUNDING`` is the Pricing-v2 self-serve plan ($45/mo → 20,000 credits/period, full rollover); ``TEAM``/``BUSINESS`` are the legacy per-seat tiers kept for historical rows during the transition. ``ENTERPRISE`` stays a manual, off-catalog sale. ``CUSTOM`` is a staff-attached negotiated Stripe price — see ``services.billing.validate_negotiated_price``.
  - `status` string, required
  - `seats` integer, required
  - `credits_remaining` integer, required: Legacy prepaid credit-pack balance in whole legacy retail credits, floored from the micro-USD ledger. The retail peg is RETAIL_MICRO_USD_PER_CREDIT = 1,000 micro-USD per credit. This balance still funds work. Drawdown cascades into this ledger after credit_balance is exhausted. Legacy retail credits and Patricia credits are different credit units; never add the raw numbers. These are display balances. Admission is decided server-side from the unrounded ledgers; neither field nor their combination determines whether Patricia will run.
  - `credit_balance` number, required: The workspace's balance in Patricia credits, a COGS-denominated credit unit, scaled from whole hundredths for display with at most two decimal places. Drawdown spends this ledger first, then cascades into the legacy credits_remaining ledger. The dashboard shows this balance as credits available. Patricia credits and legacy retail credits are different credit units; never add the raw numbers. These are display balances. Admission is decided server-side from the unrounded ledgers; neither field nor their combination determines whether Patricia will run.
  - `monthly_credit_grant` integer, required
  - `cancel_at_period_end` boolean, required
  - `current_period_end` string, nullable, required
  - `has_active_subscription` boolean, required
  - `stripe_publishable_key` string, nullable, required
  - `auto_refill` AutoRefillConfigView: GET view of a tenant's auto-refill config (the dashboard toggle + thresholds). ``enabled`` is derived from ``enabled_at`` (opt-in gate); ``armed_at`` is never exposed (engine-internal). All credit values are whole-credit ints for display.
    - `enabled` boolean, required
    - `threshold` integer, required
    - `amount` integer, required
    - `monthly_cap` integer, required
  - `has_payment_method` boolean
  - `starter_verification_required` boolean
  - `starter_verification_reason` 'card_verification' | 'challenge_verification', nullable
  - `custom_plan` CustomPlanView: A staff-attached negotiated package, as the customer's own Billing tab reads it.
    - `monthly_price_cents` integer, required
    - `monthly_credit_grant` integer, required
    - `is_current` boolean, required
  - `holds_live_subscription` boolean
  - `next_payment_attempt_at` string, nullable
  - `payment_recovery_state` 'retrying' | 'action_needed' | 'failed' | 'ended', nullable

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden. Inspect response body `code` for the specific reason (for example: PERMISSION_DENIED, EMAIL_NOT_VERIFIED, TENANT_ACCESS_REQUIRED, ROLE_UNRESOLVED)
- `404`: Not found
- `422`: Validation error

---

[API](https://skmtc.dev/patricia/apis/patricia-api.md) · [All operations](https://skmtc.dev/patricia/apis/patricia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/patricia/apis/patricia-api/revisions/0dfb44495ea1?raw)