---
title: "Billing Agent Plan"
method: GET
path: "/api/billing/agent-plan"
tags: ["billing", "team"]
---

# Billing Agent Plan

`GET /api/billing/agent-plan`

## Request

- Base URL: `https://www.oxfordledge.com` (the document declares no server; this is the origin it was published from)
- URL: `https://www.oxfordledge.com/api/billing/agent-plan`
- Auth: none declared

Active Developer plan + usage + the sellable plans (AgentPlanStatusResponse).

## Response `200`

Successful Response

- AgentPlanStatusResponse: `GET /api/billing/agent-plan` -- the caller's active Developer plan (or pay-as-you-go), this month's usage against it, and the sellable plans. Required fields are what the API-keys panel dereferences without a null-check: `used_calls`, `hard_stopped`, `month`, `plans`. `plan` and its siblings are null on pay-as-you-go by design (honest-absent, not 0).
  - `plan` string, nullable: Active AGENT_API_PLANS key, or null = pay-as-you-go.
  - `plan_name` string, nullable: Display name of the active plan, or null.
  - `price_mo` integer, nullable: USD/month of the active plan, or null.
  - `included_calls` integer, nullable: Monthly allowance of the active plan, or null.
  - `used_calls` integer, required: Class-A calls metered this calendar month (UTC).
  - `remaining_calls` integer, nullable: included - used, floored at 0; null on pay-as-you-go.
  - `hard_stopped` boolean, required: True when the NEXT call is refused (used >= included and no overage rate). 'You are blocked right now', not 'you went over'.
  - `month` string, required: The usage month, 'YYYY-MM' (UTC).
  - `plans` AgentPlanOption[], required: The sellable plans, in AGENT_API_PLANS order.
    - `key` string, required: AGENT_API_PLANS key: 'developer' | 'developer_pro'.
    - `name` string, required: Display name, e.g. 'Developer'.
    - `price_mo` integer, required: USD per month, flat recurring.
    - `included_calls` integer, required: Class-A data-read calls included per month.
    - `available` boolean, required: True iff the plan's Stripe price is configured on this deploy (STRIPE_PRICE_DEVELOPER / _PRO set). False renders a disabled button, never a checkout that 503s.
    - `overage_per_call` number, nullable: USD per successful Class-A call past the allowance, ONLY once the holder turns extra calls on (0.002 Developer / 0.001 Developer Pro); null = the plan offers no overage.
    - `overage_cap_default_usd` number, nullable: The monthly extra-call limit offered when extra calls are turned on without naming one (50 / 250).
    - `overage_cap_max_usd` number, nullable: The highest limit a holder may set (4x the plan price).
  - `overage_available` boolean: The active plan offers extra calls at a rate (false on pay-as-you-go and on a degraded consent read -- never offer an opt-in we cannot verify).
  - `overage_enabled` boolean: A LIVE mcp_tools consent row exists: extra calls are ON.
  - `overage_reconsent_required` boolean: The live consent is at a different rate than the current plan's (a plan change) -- extra calls pause until re-confirmed.
  - `overage_degraded` boolean: The consent / ledger read FAILED; the overage_* fields are unknown, not off. The next over-call is refused (fail-closed).
  - `overage_per_call_usd` number, nullable: The plan's rate (the quote).
  - `overage_agreed_per_call_usd` number, nullable: The rate on the live consent row -- the one that bills; null when off.
  - `overage_cap_usd` number, nullable: The agreed monthly limit on the live consent row; null when off.
  - `overage_cap_default_usd` number, nullable: The offered default limit.
  - `overage_cap_max_usd` number, nullable: The highest settable limit.
  - `overage_accrued_usd` number: Extra calls accrued this month under the live consent, priced at its agreed rate and clamped at its cap; not yet settled.
  - `overage_settled_usd` number: Extra calls already settled this month (settle-on-change ledger).
  - `overage_url` string, nullable: Where the rate, the cap and the route that sets it are documented.
  - `error` string, nullable: Set ONLY on the 503 (billing unavailable) / 500 (lookup failed) branches, where the route answers {error} and nothing else; the API-keys panel reads it before touching `plans` (tools/check_fe_api_key_agreement.py, 2026-09-13).

---

[API](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api.md) · [All operations](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/revisions/e832a1260f0b?raw)