Spend Caps and Usage Alerts

A spend cap saves your customer from a surprise bill. Some plans include an allowance, such as 10,000 API calls a month, and bill for every unit past it. That extra usage is called overage. A spend cap is the customer's own limit on it: after a set number of extra units, usage is refused and nothing more is recorded, just as on a plan with no overage.

Next to the cap, the customer can pick percentages of the allowance at which your backend is told. Inside a workspace, they can also cap each project.

curl -X PATCH "https://api.console.buildbase.app/api/v1/public/workspaces/$WORKSPACE_ID/quotas/api-calls" \
  -H "x-session-id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"maxOverageUnits": 5000, "notifyAtPercent": [80, 100]}'

{
  "quotaSlug": "api-calls",
  "spendCap": { "maxOverageUnits": 5000, "notifyAtPercent": [80, 100] }
}

With 10,000 calls included, that workspace can record up to 15,000 calls this period, and pays overage on 5,000 of them at most. Your webhooks get quota.threshold_reached at 8,000 calls and again at 10,000.

Who sets it

Your customer sets their own cap, so your app calls one of these routes for them:

Both take the signed-in user's session in x-session-id. There's no SDK hook for setting a cap yet, so call the route from your settings screen or your backend. A person's cap takes maxOverageUnits and notifyAtPercent. Only a workspace can have partitionCaps.

The body

Send any of these fields:

Send at least one field. Whatever you leave out stays as it was. Partition caps are updated one key at a time, so sending one doesn't clear the others. The response is the cap as it now stands.

What a cap changes

• Recording. A unit that would go past maxOverageUnits is refused, and nothing is recorded, exactly as on a plan without overage. The refusal is 402 QUOTA_EXHAUSTED, with quotaSlug and resetsAt, and its message names the cap. See Quotas for handling it.
• Nothing else on a hard allowance. A cap only limits overage. So it does nothing on a quota whose plan doesn't bill overage, during a trial (which is always held to the allowance), or on an unlimited quota.
• The check routes. POST /api/v1/public/me/entitlements/check, and the org's GET /api/subscriptions/users/entitlements/check, now count the cap. A quota's remaining is the allowance left plus the overage the cap still allows, instead of unlimited.
• Reading it back. GET .../quotas/:slug carries spendCap beside usage, included, available and resetsAt. The workspace's route needs permission to view usage.

A new cap can take up to ten seconds to apply everywhere. Every recording reads the cap, and each server process keeps its copy for up to ten seconds.

Usage alerts

Usage alerts tell you when a customer is getting close to their allowance, so you can warn them before they pay extra. Each time a recording takes usage from below one of the chosen percentages to at or above it, BuildBase sends quota.threshold_reached for that percentage, once a period, to your webhooks and workflows. It's one of the 239 events in the catalog:

{
  "subjectType": "workspace",
  "subjectId": "66f0c1d2e3a4b5c6d7e8f901",
  "workspaceId": "66f0c1d2e3a4b5c6d7e8f901",
  "quotaSlug": "api-calls",
  "percent": 80,
  "used": 8012,
  "included": 10000,
  "resetsAt": "2026-11-01T00:00:00.000Z"
}

If one burst of usage jumps past two percentages at once, only the higher one fires. BuildBase doesn't message your customer for you: send the email or the in-app message from your webhook handler or a workflow. A person's alert names the person and no workspace.

Separately, the first unit of overage fires quota.limit_exceeded, and BuildBase emails that one to the owner. See Webhooks.

A cap per project

Inside one workspace, you can stop a single project from using up the whole allowance. Record usage with a partitionKey, such as the project's id, and it counts toward that partition as well as toward the workspace. A capped partition gets whichever is smaller: its own room left, or the workspace's.

curl -X PATCH "https://api.console.buildbase.app/api/v1/public/workspaces/$WORKSPACE_ID/quotas/api-calls" \
  -H "x-session-id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"partitionCaps": {"project-42": 2000, "project-7": null}}'

Record usage with the same key, on POST /api/v1/public/workspaces/:workspaceId/subscription/usage with partitionKey in the body. A unit past the partition's cap is refused with 402 QUOTA_EXHAUSTED, naming the partition. To read a partition's usage, GET .../quotas/api-calls?partitionKey=project-42 answers partitionUsed, plus partitionCap and partitionAvailable when the partition has a cap.

A key is 1 to 128 letters, digits, dots, underscores, colons or hyphens (^[A-Za-z0-9._:-]{1,128}$). It can't be pool or start with member:, because per-member quotas use those. One quota can cap at most 100 partitions. A change past that is refused with 400 on partitionCaps, so remove a cap with null before you add another.

Next steps

• Quotas - Record usage and handle the refusal.
• Family and group plans - Give each member an allowance of their own.
• Claims - Count keys, projects or installed apps against a limit.