Set Overage Enabled
const url = 'https://example.com/api/billing/overage?organization_id=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"enabled":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url 'https://example.com/api/billing/overage?organization_id=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "enabled": true }'Turn billed over-cap usage on or off for this organization (§13.3).
ON lets devices register past included_devices and data points ingest
past included_datapoints_month, with the excess billed at the tier’s
overage rates; OFF stops both at the cap. The asset cap is unaffected in
either direction — no asset overage price exists, so it is hard in every
state.
Same two gates as checkout and cancel: org_owner and
_require_billing_owner. This flag is a standing consent to be charged
more than the tier price, so it belongs to the identity whose payment
instrument would carry the charge (§3.8) — not to any of an org’s several
OWNERs, and not to a superuser.
Turning it ON requires a tier that permits it. Free’s
features_json.overage_allowed is false and so is every non-tier org’s
answer, since a grandfathered à la carte org has no features_json at
all: overage was never part of that deal, device_cap will keep refusing
it at 403 regardless, and accepting a flag that changes nothing would be
the kind of silent no-op a billing API must not have. Both refuse with 409
overage_unavailable.
Turning it OFF is always accepted, including for the orgs above. A
customer must never be unable to reduce their own billing exposure, and
writing false over false converges rather than misleads.
Authorizations
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “ Query Parameters ”Request Bodyrequired
Section titled “ Request Bodyrequired ”PATCH /api/billing/overage — the org owner’s over-cap billing consent.
object
Example generated
{ "enabled": true}Responses
Section titled “ Responses ”Successful Response
PATCH /api/billing/overage — the state as it now stands.
Deliberately a confirmation rather than a second copy of
BillingSubscriptionResponse: the console re-reads /subscription for
usage and entitlements anyway, and mirroring that shape here would give
two endpoints that must be kept in step for no gain. Same posture as
CancelSubscriptionResponse.
object
Example generated
{ "organization_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "overage_enabled": true, "plan_code": "example"}Validation Error
object
object
object
Example generated
{ "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ]}