# Plans, the trial, and reading your usage

This page is the customer-facing description of how a Bucker Cloud organization is billed and how to
see what it used. Every number on it is read from the billing module (`GET /billing/plans`), which is
also what the pricing page publishes and what quota enforcement applies. If this page and that
endpoint ever disagree, the endpoint is right and this page is a bug.

## What a plan limits

- **Events per month** and **retention** differ by tier. Going over the event allowance degrades to
  sampling. It is never billed as overage.
- **Human seats are unlimited** on every tier.
- **Agent principals are unlimited** on every tier. An earlier price list published limits of 1, 5
  and 25 that nothing enforced; they were removed rather than kept as a claim. What costs money is
  the work an agent does, and that is metered per verified fix.
- **Verified fixes** are included per month, then priced per fix. Unused credits roll over (capped at
  three months of the allotment) and never expire.

## Add-ons: Mitigate

**Mitigate** is the ability to pull a production lever against an issue: request and apply a
mitigation (kill switch, variant pin, rollback and the other typed levers) or an edge hotfix.
`GET /billing/plans` publishes each plan's `addOns.mitigate` as `included`, `add_on` or `absent`,
and `GET /orgs/{org}/billing/subscription` states your organization's standing in
`addOns.mitigate` (`entitled`, and a `source` such as `included` or `not_on_plan`).

| Plan | Mitigate |
| --- | --- |
| Free | not available |
| Pro | included |
| Team | included |
| Enterprise | included |

Mitigate is part of every paid plan, and there is nothing extra to buy: no plan sells it as a
separate add-on, so there is no add-on price and no add-on line on an invoice. That includes the
14-day Pro trial, which can use the levers. The code reads the placement from one table
(`ADD_ON_PLACEMENT` in `domain/src/modules/billing/plans.ts`), so the pricing page, the API and the
dashboard always agree with what is enforced.

- On Free, the Mitigate page and the issue's Mitigate section say the levers are not on the plan
  instead of disappearing, and the API refuses a new lever with a 403 that names the add-on and
  the plan that includes it (Pro).
- **Nothing already live is stranded.** Losing Mitigate (a downgrade to Free) stops new levers
  from being requested or applied. You can still list, read, verify and revert what is live, and
  manage its reversal debt.

## The 14-day Pro trial

An organization on Free can start a Pro trial from **Settings, Billing**, or with
`POST /orgs/{org}/billing/trial`.

- No card is asked for and nothing is charged.
- It runs fourteen days, and it is available **once per organization**, even after it ends.
- If you do nothing, the organization returns to Free by itself when the trial ends. Pro-only
  settings stay stored; they just stop applying.
- To keep Pro, change plan from the same page. The move is then quoted and charged as Free to Pro,
  and a payment method is required first.

Starting a trial needs the billing permission (an owner or the dedicated billing role).

## Annual terms

An annual term is ten months' price for twelve (two months free) on Pro or Team. It is **arranged
with sales**, not bought in the dashboard: there is no self-serve annual subscription yet, because
the invoice and the event allowance both still run monthly. Say you want an annual term in the
contact form on the pricing page, or mention it in your message.

- The year is invoiced once, up front, at the annual price `GET /billing/plans` publishes
  (`annualPriceCents`). You are not also billed monthly for the same plan.
- Your event allowance and other monthly limits still reset every month during the term.
- Mitigate is included on Pro and Team, so the annual price covers it; there is no add-on to add.

## Talking to sales

The form at the bottom of `/pricing` sends a message to the operator console of the deployment you
are talking to. It is not forwarded to a marketing tool. Nothing about the sender is stored beyond
what the form asks for.

## Reading your usage

**Settings, Billing, Usage this period** shows accepted, sampled and dropped events against your
allowance, and below the totals a **projection**: where the period is heading if the rest of it
looks like the part already elapsed.

- It is a **straight line**, and says so. It appears once a day of the period has elapsed, only for
  the current period and only for the whole organization (not when narrowed to one project).
- If the pace reaches your allowance, it names roughly when. After that, events are sampled, not
  charged.
- **Projected spend** is your plan's flat price plus the metered fixes seen so far, projected
  linearly. Events add nothing. It is an estimate, not a bill.

### Export and attribution

For reconciliation, the same data is available broken down **by project, key and item type**:

| Route | Returns |
| --- | --- |
| `GET /orgs/{org}/billing/usage/attribution` | JSON rows: `projectSlug`, `keyId`, `keyName`, `category`, `accepted`, `sampled`, `billable`, `dropped` |
| `GET /orgs/{org}/billing/usage/export?format=csv` | The same rows as CSV |
| `GET /orgs/{org}/billing/usage/export?format=jsonl` | The same rows as JSON Lines |

Both accept `from`, `to` and `projectId`; the default is the current billing period. The rows are
folded from the same ingest ledger as the invoice, so they **sum to the usage summary's** `billable`
and `dropped` for the same period. The export stops at 10,000 rows and says so in the
`x-bucker-export-truncated` header. An export of 1,000 rows or more writes one `billing.usage.export`
row to the audit log.

Who sees which rows: anyone with the billing permission sees every project. Anyone else sees only
the projects they could open, so this is not a way around team boundaries.