---
title: "Billing Agent Plan Overage"
method: POST
path: "/api/billing/agent-plan/overage"
tags: ["billing"]
---

# Billing Agent Plan Overage

`POST /api/billing/agent-plan/overage`

## 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/overage`
- Auth: none declared

Turn Developer-plan extra calls on with a monthly limit, change it, or turn them off. Body: {cap_usd}.

## Response `200`

Successful Response

- AgentPlanOverageResponse: `POST /api/billing/agent-plan/overage` -- turn extra calls on with a monthly limit (the consent act: the rate and the limit shown by GET are what bill), change the limit, or turn them off (`cap_usd: 0`). B2, 2026-09-14. Success = `status == "ok"`; refusals ride the api_error envelope with a `reason` from the closed vocabulary (no_plan / overage_not_offered / cap_invalid / cap_out_of_range / consent_degraded / billing_unavailable).
  - `status` string, required: 'ok' on a write.
  - `plan` string, nullable: The active plan key the consent was recorded for.
  - `overage_enabled` boolean, required: Extra calls are ON after this write.
  - `overage_per_call_usd` number, nullable: The rate recorded on the consent row.
  - `overage_cap_usd` number, nullable: The limit recorded on the 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.
  - `consent_id` integer, nullable: metered_consents.id of the new live row; null when off.
  - `url` string, nullable: Where the terms are documented.
  - `error` string, nullable: Set only on a refusal branch.
  - `message` string, nullable: Set only on a refusal branch (api_error envelope).
  - `reason` string, nullable: Refusal reason from the closed vocabulary; only on a refusal.

---

[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)