Billing & quotas

For agents: get_usage(org="acme") (exact daily accepted events, plan, overage flag, credit balance), get_billing_plans(org="acme") (catalog + whether checkout is configured), set_overage(org="acme", enabled=true) (org:admin, audited). Upgrades happen in the dashboard — there is no checkout tool.

One meter

1 error = 1 event, 1 transaction = 1 event. Spans, sessions, breadcrumbs, and client reports are free. There is no per-seat pricing for viewers.

Paid plans have unlimited projects. Viewers are unlimited everywhere.

Exact metering

Accepted events are counted by a per-organization Durable Object (OrgQuota) and flushed to the control database as usage_daily rows by category — this is the number on the usage page and the invoice. The sampled analytics index is never used for billing. Filtered events, SDK-side drops (client reports), and rate-limited events are recorded as outcomes for transparency but are not billed.

GET /v1/orgs/{org}/usage returns the plan, overageEnabled, daily[] (date, category, accepted) for the last 31 days, and credits (balance, entries with expiry, last invoice application, and appliesToInvoices / notAppliedReason: whether anything can deduct them).

Hard cap versus overage

• Default: hard cap. When the period's accepted events reach the plan allowance plus a 10% grace, the quota object writes a flag that ingest reads; further envelopes get 429 with X-Sentry-Rate-Limits and Retry-After, and SDKs back off. Nothing is billed beyond the plan.
• Overage opt-in (POST /v1/orgs/{org}/billing/overage {"enabled": true}, org:admin): the flag is never written; events above the allowance are billed at the plan's overage rate. Free has no overage.
• Counters reset on the organization's billing anchor day (nightly job).

Credits

Credits (launch, migration, startup programs) live in a ledger and apply automatically on invoice creation:

• Cover at most 50% of any invoice, across all credits combined; individual credits may carry a lower per-credit percentage.
• Never apply to tax — only the pre-tax subtotal.
• Active balance is capped at $1,000 per organization; grants clamp to the room left.
• Drawn FIFO by nearest expiry. The balance and expiry dates are visible in get_usage and on the usage page.

Promotional credits are applied by discounting the invoice before it is finalized, which only works for Stripe-billed organizations. Polar issues its own invoices as the seller of record, so credits granted to a Polar-billed organization cannot come off its bill. The balance says so rather than reading as money: credits.appliesToInvoices is false with a notAppliedReason in GET …/usage and get_usage, and Settings → Billing labels it "not applied" and gives the reason. With no credits granted and none that could apply, the Credits panel is not shown at all. An organization not yet billed is judged by the provider it would be billed by. Tell us if you are holding a credit that does not apply. Fix-agent credit packs, which are purchases rather than discounts, work on both providers.

Checkout and portal

Who you are buying from

Bugwatch supports more than one payment provider, and which one bills you changes who the seller is — so it is stated, not hidden:

GET /v1/orgs/{org}/billing/plans reports the active one under provider (id, name, merchantOfRecord), and Settings → Billing shows it above the plan ladder. Your organization is assigned a provider the first time it pays and stays on it: if the default changes later, your existing subscription, portal, and invoices do not move.

The endpoints

GET /v1/orgs/{org}/billing/plans returns every plan with purchasable set when a provider is configured and a product exists for it. Upgrading is POST /v1/orgs/{org}/billing/checkout {"plan": "team", "returnPath": "/o/acme/settings"} → {"url", "provider"} (a redirect to the provider's hosted checkout); managing cards, invoices, and cancellation is POST …/billing/portal → {"url", "provider"}. Both require org:admin, return 501 when no provider is configured, and are deliberately not exposed as MCP tools — purchases stay human-initiated. Plan changes come back through the provider's webhooks and update the allowance immediately.

Cancelling leaves the plan in place until the period you have paid for runs out; the drop to Free happens at expiry, not at the moment you cancel.

What agents can do here

What the plan enforces

• Project cap. The Free plan includes 5 projects. Creating a sixth returns 402 with {"error": "project limit reached …", "limit": 5, "plan": "free"} from POST /v1/orgs/{org}/projects and from the create_project tool. Paid plans are unlimited.
• Retention follows the plan. New projects are created in the plan's tier (30 days on Free, 90 days on every paid plan). When a plan changes — Checkout, a subscription update, or a downgrade to Free — every project in the organization moves to the new tier within seconds, for events received from then on. Events already stored keep the retention they were written with; nothing is deleted early on a downgrade, and nothing is extended retroactively on an upgrade.
• Period resets. Exact usage counters reset on your billing anchor day (the 1st unless your subscription anchored elsewhere; 29–31 clamp to the last day of shorter months). Resets are idempotent per period, so a delayed nightly run never double-resets or skips a month.

How overage is billed

With metered overage on, the nightly job computes each day's overage events — the part of that day's accepted errors and transactions that pushed the period's cumulative total past the allowance — from the exact per-day counts, and reports it to whichever provider bills your organization — a Stripe billing meter event, or a Polar usage event — under the identifier org:date. Each org-day is reported once; the last seven days are re-checked every night, so a missed run catches up and a retried run never double-bills. Days with no overage are recorded with zero and no call to the provider. So are days your organization was not billable for overage at all — overage off, or a plan without it — because each day's decision is taken once, the night after it happens, and never revisited: switching overage on does not bill the week before you switched it on, switching it off does not erase days you had already agreed to, and changing plan mid-period does not re-price days already recorded against your old allowance. Settings → Billing shows the events reported so far this period and the last reported day; the same numbers come back from get_usage under overage.