# 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.

## What a unit is

The allowance is one number of **units** a month, not a count of events. One error is 1 unit;
every other kind of data is priced against it by what it costs Bucker to take in, process and keep,
and some kinds weigh nothing. There is no separate meter, price or invoice line for any kind of
data: a plan has one flat price and one allowance in units, and the weights below are the whole
price list for data.

| What you send | Category | Units each |
| --- | --- | --- |
| An error event | `error` | 1 |
| A replay segment (two items, the event and the recording) | `replay` | 1 an item |
| An attachment | `attachment` | 1 per started 256 KiB |
| A span (an OpenTelemetry span, an SDK span, each span of a Sentry transaction) | `transaction` | 0.2 |
| A profile (Bucker does not accept profiler output yet) | `profile` | 0.2 |
| A log record | `log` | 0.05 |
| A product-analytics event (Bucker does not store these yet) | `product` | 0.05, whether the user is anonymous, identified or linked to an account |
| A metric data point | `metric` | 0.05, a histogram point being one point whatever its buckets |
| A synced source row, inserted or changed (sources are not live yet) | `source_row` | 0.01 |
| A release-health session | `session` | 0 |
| User feedback and survey responses | `feedback` | 0 |
| Bucker's own bookkeeping and client reports | `internal` | 0 |

Two things the table does not show. **Identification never changes a bill:** a product event costs
the same with no user attached as with a user and three accounts, and there is no add-on for either.
**Metrics have their own row** on the usage page, apart from logs; before that split, data points
were filed as log records at this same weight, so nothing you were charged has moved.

**Over your allowance, data is sampled, never billed.** Each kind degrades in the way that keeps it
useful, and everything discarded is counted on the drops panel with the reason:

- Errors, spans, logs, metrics, replays and the rest are sampled to a thin slice. Sent through an
  SDK, the first few of each kind per minute are always kept before the slice, so something new is
  still seen; sent over OpenTelemetry, each request keeps its slice.
- **Product events are sampled by person.** A person the sampler keeps is kept on every event, so a
  kept person's funnel is whole; and the first few events of each new event name are always kept.
- **Feedback is not sampled.** Past a daily ceiling per project (10,000 answers on Free, 100,000 on a
  paid plan) the prompts that ask for feedback are shown less; an answer already sent is stored, and
  an envelope carrying only feedback is kept whole over your allowance. Only the hard ceiling below
  refuses it.
- A **source** has a monthly cap; at the cap it pauses, keeping the rows it has, and says so.
- At ten times the allowance requests are refused with a `429`, and an SDK backs off.

**A request is never free.** Deciding whether to take a request costs at least one unit, so a stream
of tiny requests cannot be a free channel. The monthly figure counts the items themselves, so it can
read lower than the sum of those decisions: a thousand one-item requests of a 0.05 category are a
thousand units when Bucker decides and fifty in the month. Whether that floor is recorded in the
monthly figure is an open decision.

## 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 your **weighted units** 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. The bar, the percentage, the 80, 90 and 100 percent notices and the projection are
all computed from the same figure, the one the accept edge enforces: `events.units` in
`GET /orgs/{org}/billing/usage`. The raw item count (`events.billable`) stays beside it as the
headline, labelled as items, and each category row carries its `units` too. A project sending
100,000 log lines is at 5,000 units, and every surface says 5,000.

### The weighted reading and its receipts

`GET /orgs/{org}/billing/usage/weighted` (and the `usage_get` tool in the MCP `platform` toolset)
returns what enforcement counts and where it came from:

- `units` (weighted, the figure compared with `allowanceUnits`) and `items` (raw), with the per
  category rows (`weight`, `items`, `units`). The one-unit-per-request floor is "decision only, not
  ledgered": it applies when Bucker decides whether to sample an envelope and is in neither total.
- `basis`: `rollup` (the hourly `usage_hours` fold), `ledger` (the outcome ledger itself) or
  `rollup_and_ledger`, and why the ledger was read: the rollup is not live, has not reached the most
  recent hours, or the period is older than it holds. The figure is the same whichever was read.
- `receipts`: for each category, door and UTC day, what was **kept**, **sampled**, **dropped** and
  **floor-kept**, and the kept rate. The ledger records no door, so rows read from it say
  `unattributed`.

### FOCUS export

`GET /orgs/{org}/billing/usage/focus.csv` serves the period as FinOps Open Cost and Usage
Specification rows: one usage row per project, category and day (quantity in weighted units, cost 0
because flat plans never bill event volume) and one charge row per verified fix, with money. It needs
the billing permission (an owner or the billing role). Custom columns are prefixed `x_`.

- 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.

### Your bill in the cost ledger

The same units are in the cost ledger under the source `bucker`, split by service and release and
allocated to the same owners as your infrastructure and AI spend: `cost_status_get` with
`source: bucker`, or the attribution block of `usage_get`, which says when it was last derived. The
plan price is spread over your included units (a unit past the allowance costs nothing, because plans
never bill overage) and a month that ends under its allowance shows the unused part as its own line,
so a closed month adds up to the plan price. It is an allocation of a flat fee, labelled as an
estimate beside the one billed line for the plan itself. Anyone who can read the project sees the
units; the money needs `cost:read`. See `cost.md`.

### 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`, `units` (the CSV and JSON Lines files keep their columns) |
| `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.
