Spend control

Generated from packages/api/src/billing/spend-control.controller.ts by packages/docs/tools/generate-reference.mjs. Every example is a real exchange recorded against the control plane by packages/api/src/testing/reference-examples.spec.ts, with ids from that run. Credentials in the formats this product issues (kr_, krsk_, krses_, JWTs) and values under credential-named fields (password, *_secret, *_token, *_key, lookup_hash) are elided at record time; the recorded file and every page of this site are swept for credential shapes (kr_, krsk_, krses_, JWTs, URLs carrying a password, password fields) before either is accepted. Do not edit by hand: src/reference.spec.ts regenerates it and fails on a difference.

PATCH /v1/billing/subscription -- the customer's own maximum monthly overage, and nothing else about the subscription.

Q1: there is no bill/block switch. 0 (the default) allows no overage and blocks at the plan's included tenants; a positive amount is the overage, in cents, the owner opts in to. Raising it is a commitment to spend, so it is refused to a test credential (assertLiveCredential) and to any machine principal, including a live secret key (assertPersonOwner) -- the vendor's backend must not be able to raise its own bill.

Changing the cap re-arms the once-a-month warnings, or a customer who raises it and crosses the new one would hear nothing for the rest of the month. Lowering it below what the workspace already holds un-bills nothing: tenants already active this month keep counting; only new ones are refused.

PATCH /v1/billing/subscription

Answers 200 on success.

Authentication.

A krsk_ secret key or a krses_ dashboard session, as Authorization: Bearer.

Body. Validated by this schema, from the control plane's own source:

The ceiling is budget_cap_cents <= 100000000 in 0017: EUR 1 M a month of overage, and a bound that keeps the ceiling's integer division from overflowing. Validated here so a bad value is a 400 naming the field.

const UpdateSpendControl = z.object({
  budget_cap_cents: z.number().int().min(0).max(100_000_000),
});

Example.

Request

curl https://api.keyringdev.com/v1/billing/subscription \
  -X PATCH \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "budget_cap_cents": 15000
  }'

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": "subscription",
  "plan_code": "free",
  "included_tenants": 3,
  "overage_cents_per_tenant": null,
  "currency": "EUR",
  "amount_cents": 0,
  "interval": "month",
  "status": "none",
  "collection_state": "current",
  "grace_until": null,
  "active_tenants_this_month": 1,
  "budget_cap_cents": 15000,
  "effective_tenant_ceiling": 3,
  "tenants_held": 1
}

PATCH /v1/billing/subscription

On this page