| 1 | # Billing operations: costs, margin and prices |
| 2 | |
| 3 | How g1t checks what it charges against what Cloudflare charges it, keeps |
| 4 | prices at cost plus 20%, and tells staff when the margin slips. Internal. |
| 5 | Code: `services/billing/src/costs.rs` (reading the bill), `cycle.rs` |
| 6 | (Cloudflare's billing cycle, list prices and included amounts), `margin.rs` |
| 7 | (reconciliation, drift, alerts), `pricing.rs` (versions, proposals, |
| 8 | notice), `keeper.rs` (sandbox and Workers for Platforms measurements), |
| 9 | `budget.rs` (what g1t pays for itself, and its caps; see |
| 10 | [Spend caps](#spend-caps)). |
| 11 | Page: sudo **Costs & margin** (`/costs`). |
| 12 | |
| 13 | Several Cloudflare products g1t runs on are new. Artifacts bills |
| 14 | "operations" from 2026-10-14 without defining them (see |
| 15 | [ARTIFACTS.md](ARTIFACTS.md), M1). So nothing here hard-codes a product |
| 16 | list or a unit: every line Cloudflare bills is kept, and how a line maps |
| 17 | to what g1t sells is data you change from sudo, without a deploy. |
| 18 | |
| 19 | ## Data sources |
| 20 | |
| 21 | | Source | What | Where it lands | |
| 22 | | --- | --- | --- | |
| 23 | | Billable usage, `GET /accounts/{account}/billable-usage?from=&to=` | One row per service per day in FOCUS columns: `ServiceFamilyName`, `ServiceName`, `ChargePeriodStart`, `ConsumedQuantity` (else `PricingQuantity`), `ContractedCost` / `BilledCost` / `EffectiveCost`. Every page is read (`result_info`: `cursor`, else `total_pages`), over whole billing cycles (see [The billing cycle](#the-billing-cycle)). Every product g1t uses appears here once it is used: Workers, Workers for Platforms, D1, KV, R2, Queues, Containers, Durable Objects, Artifacts, Browser Rendering, Workers AI, Vectorize, Cloudflare for SaaS, Email. While a cycle is open its rows carry no cost; `ListCost` is never taken, since it is before the included amounts. | `cost_lines`, source `billable_usage`: `quantity` (consumed), `billed_usd` (Cloudflare's own cost), `billable_quantity` and `cost_usd` (over the cycle), `basis`; the read itself in `cost_reads` | |
| 24 | | GraphQL `artifactsEventsAdaptiveGroups` | Artifacts' own count by `date`, `eventType` and `repositoryName`. Operations are `create`, `fork`, `push`, `pull`, `delete`; errors (`rateLimited`, `serverError`, …) are kept but not counted. | `cost_lines`, source `artifacts_events`; per workspace (from the store key `<workspace>--<repo>`; a pull request's working copy, `pulls--<id>`, is its repository's workspace's, from repos' `pull_owners`) in `own_counts` as `cloudflare_git` | |
| 25 | | GraphQL `aiGatewayRequestsAdaptiveGroups`, filtered to `AI_GATEWAY_ID` | What AI Gateway priced g1t's own provider traffic at, by `date`, `provider` and `model`: `count`, `sum.cost` (dollars), `sum.tokensIn`/`tokensOut`/`cacheReadTokens`/`cacheWriteTokens`; asked twice in one query, filtered `wholesale: 0` and `wholesale: 1`. `wholesale` is never a dimension: grouped by it, Cloudflare answers no rows and no error (until 2026-10-08 that left the gateway's side empty while it had logged $11.11). Read over its own window: the last 31 days until it has answered with a line, then the last few. Field names checked against Cloudflare's schema (introspection of `AccountAiGatewayRequestsAdaptiveGroups{Sum,Dimensions,Filter_InputObject}`). An adaptive (sampled) dataset: an estimate, close at g1t's volumes. Only g1t's hosted models go through this gateway: a workspace's own provider is called at its own address, never here. | `cost_lines`, source `ai_gateway`, product `ai_gateway_requests`: per day and model a line `<provider>_<model>` (requests, at the gateway's cost), and at no cost `…__tokens`, `…__cache_read_tokens`, `…__cache_write_tokens`; Cloudflare-billed (unified billing) requests are prefixed `wholesale__`. Mapped to `models` (migration 0036). A re-read day replaces all its gateway lines. | |
| 26 | | The ledger | Every charge: its cost at the price book's cost, what it was charged at price, what paid for it. | read, never written | |
| 27 | | `pending_usage` | Month-end meters (git, storage, scans, embeddings, the cache) as they stand. | snapshotted daily into `pending_days` | |
| 28 | | `plan_payments` | The plan's $20. | read | |
| 29 | | repos `git_operations` | Operations customers are charged for, per workspace, counted by repos through its `operation_mapping`. | `own_counts` meter `git_operations` | |
| 30 | | Subscriptions, `GET /accounts/{account}/subscriptions` | What g1t pays each month whatever it uses (Workers Paid, add-ons): each subscription that is paid, trialing or awaiting payment, at its price over its frequency; and `current_period_start` of the monthly one, the day every billing cycle starts. Not on the billable-usage bill. Read first in the daily run, with the bill's token; a failure is logged and the last read stays. | `cf_subscriptions` (one row; `cycle_start`) | |
| 31 | | repos `artifacts_usage` | Every raw meter of the git store (`git.fetch`, `git.receive_pack`, `binding.*`, …) per day and workspace, with repos' `operation_mapping`. | `own_counts` meters `artifacts_<raw meter>`, and `cost_operations` (raw counts × the mapping's `cost_operations`: what g1t expects Cloudflare to bill) | |
| 32 | |
| 33 | A meter's slug is Cloudflare's name lower-cased with words joined by `_` |
| 34 | and the "(First … included)" note dropped: `Workers for Platforms CPU ms |
| 35 | (First 60M ms are included)` under `Workers` is product `workers`, meter |
| 36 | `workers_for_platforms_cpu_ms`. Several rows of the same day and meter |
| 37 | (regions, tiers) are added together before they are stored. |
| 38 | |
| 39 | ## The billing cycle |
| 40 | |
| 41 | Cloudflare bills usage per billing cycle: a month from the day the |
| 42 | account's subscription renews. g1t's account renews on the 28th, so a cycle |
| 43 | runs from the 28th to the 27th (Sep 28 to Oct 27, 2026). Each meter's |
| 44 | included amount ("first 30M are included") is the account's, once a cycle: |
| 45 | not a day's, not a calendar month's, and not per product. Code: |
| 46 | `services/billing/src/cycle.rs`. |
| 47 | |
| 48 | - **When a cycle starts**: `current_period_start` of the monthly |
| 49 | subscription, from the daily read of the subscriptions |
| 50 | (`cf_subscriptions.cycle_start`). Until that has worked, |
| 51 | `CLOUDFLARE_BILLING_DAY` on g1t-billing (`28`), else the 1st. |
| 52 | - **What is read**: the whole current cycle, every run, and the cycle |
| 53 | before while it is in its first 4 days (Cloudflare posts a day a day or |
| 54 | two late and restates recent days) or when nothing has been read yet. |
| 55 | Every page of the answer. The days read replace what was kept for them. |
| 56 | - **What a meter costs**: where Cloudflare put a cost on any of a meter's |
| 57 | lines in the cycle, that cost, line by line (`basis` `cloudflare`). |
| 58 | Otherwise the list price past the included amount (`basis` `list`), on |
| 59 | the days the cycle's running total passes it: a cycle that crosses the |
| 60 | included amount on the 7th has all of its cost on the 7th and after, as |
| 61 | on Cloudflare's Billable usage page. Meters priced per million |
| 62 | (requests, CPU ms, rows, operations) are billed in whole millions: |
| 63 | 9.16M CPU ms past the included 30M is 10M, $0.20. A meter with no list |
| 64 | price is costed at $0 (`basis` `none`), and sudo lists it. |
| 65 | - **List prices** (`cycle::LIST_PRICES`), each with its included amount |
| 66 | per cycle: |
| 67 | |
| 68 | | Meter | Included | Price | |
| 69 | | --- | --- | --- | |
| 70 | | Workers standard requests | 10M | $0.30 per million | |
| 71 | | Workers CPU ms | 30M | $0.02 per million | |
| 72 | | Workers for Platforms requests | 20M | $0.30 per million | |
| 73 | | Workers for Platforms CPU ms | 60M | $0.02 per million | |
| 74 | | Workers for Platforms scripts | 1,000 | $0.02 each | |
| 75 | | Workers Logs events | 20M | $0.60 per million | |
| 76 | | D1 rows read / written | 25B / 50M | $0.001 / $1.00 per million | |
| 77 | | D1 storage | 5 GB-month | $0.75 per GB-month | |
| 78 | | KV reads / writes, lists, deletes | 10M / 1M each | $0.50 / $5.00 per million | |
| 79 | | KV storage | 1 GB | $0.50 per GB-month | |
| 80 | | R2 Class A / Class B operations | 1M / 10M | $4.50 / $0.36 per million | |
| 81 | | Durable Objects requests | 1M | $0.15 per million | |
| 82 | | Durable Objects duration | 400,000 GB-s | $12.50 per million GB-s | |
| 83 | | Durable Objects SQL rows read / written | 25B / 50M | $0.001 / $1.00 per million | |
| 84 | | Durable Objects SQL storage | 5 GB-month | $0.20 per GB-month | |
| 85 | | Queues operations | 1M | $0.40 per million | |
| 86 | | Containers memory | 25 GiB-hours (90,000 GiB-s) | $0.0000025 per GiB-second | |
| 87 | | Containers vCPU | 375 vCPU-minutes (22,500 vCPU-s) | $0.000020 per vCPU-second | |
| 88 | | Containers disk | 200 GB-hours (720,000 GB-s) | $0.00000007 per GB-second | |
| 89 | | Containers egress, North America and Europe / elsewhere | 1 TB / 500 GB | $0.025 / $0.04 per GB | |
| 90 | | Vectorize queried / stored dimensions | 50M / 10M | $0.01 per million / $0.05 per 100 million | |
| 91 | | Workers AI neurons | 10,000 a day | $0.011 per 1,000 | |
| 92 | |
| 93 | Not priced yet, so $0 until Cloudflare's lines carry a cost: Artifacts |
| 94 | (billed from 2026-10-14), Email Service, Browser Rendering, R2 storage, |
| 95 | Cloudflare for SaaS. When Cloudflare changes a price or an included |
| 96 | amount, change the table and its test in the same pull request. |
| 97 | - **Projection**: the cycle's cost so far over the days elapsed, times the |
| 98 | cycle's days, as Cloudflare's page projects it ($0.29 over 12 days of a |
| 99 | 30-day cycle is $0.73). |
| 100 | - **Subscriptions** (Workers Paid and Workers for Platforms, $30 a month) |
| 101 | accrue day by day: each day is its cycle's share of the month's price. |
| 102 | The statement's range and g1t's own spend (the calendar month so far) both |
| 103 | add up the same days, so they never disagree about a day. |
| 104 | |
| 105 | Sudo's Bill & pricing page opens with **This billing cycle**: each meter's |
| 106 | use, what the cycle includes, what is past it and its cost, the total so |
| 107 | far, the average day, the projection and the subscriptions. Under it, what |
| 108 | the last read got back (`cost_reads`): rows, pages, how many rows had a |
| 109 | consumed quantity and how many only a pricing quantity, and how many carried |
| 110 | Cloudflare's own cost. |
| 111 | |
| 112 | To check the figures against Cloudflare: in the dashboard, Billing → |
| 113 | Billable usage, for the same cycle. The total so far, the projection and |
| 114 | each meter's total and billable quantity should agree within a cent. If |
| 115 | they do not, read the answer itself with a token with Billing Read: |
| 116 | `GET https://api.cloudflare.com/client/v4/accounts/{account}/billable-usage?from=<cycle start>&to=<today>`, |
| 117 | and compare, for `Workers CPU ms` and `Container Memory`, the |
| 118 | `ConsumedQuantity`, `PricingQuantity`, `PricingUnit` and the cost columns, |
| 119 | and `result_info` for more pages. |
| 120 | |
| 121 | ## Credentials |
| 122 | |
| 123 | | Secret on g1t-billing | Permissions | Used for | |
| 124 | | --- | --- | --- | |
| 125 | | `CLOUDFLARE_BILLING_TOKEN` (optional) | Account: **Billing Read**, Account: **Account Analytics Read**, for the g1t account only | Reading the bill, the Artifacts events and the subscriptions | |
| 126 | | `CLOUDFLARE_USAGE_TOKEN` (exists) | Billing Read, Account Analytics Read, AI Gateway Read | The keeper (settling runs from the gateway's logs); also the bill when `CLOUDFLARE_BILLING_TOKEN` is not set. AI Gateway's analytics are read with this token first and, if that is refused, with the bill's (a token without Account Analytics Read gets an error). When the answer has no rows, billing asks the REST API for the gateway with the same token: 403 means the token lacks AI Gateway Read, 404 that `AI_GATEWAY_ID` names no gateway, 200 that nothing went through it; the `models` drift says which | |
| 127 | |
| 128 | With neither, the daily run reconciles only what g1t counted itself, and |
| 129 | the page says the bill cannot be read. Nothing fails. To set the scoped one: |
| 130 | |
| 131 | 1. Cloudflare dashboard → My Profile → API Tokens → Create Token → Custom token. |
| 132 | 2. Permissions: Account · Billing · Read; Account · Account Analytics · Read. |
| 133 | 3. Account resources: Include · the g1t account. No zone permissions. |
| 134 | 4. `cd services/billing && npx wrangler secret put CLOUDFLARE_BILLING_TOKEN`. |
| 135 | 5. In sudo, Costs & margin → **Run the analysis now**. |
| 136 | |
| 137 | Alerts are emailed through the `EMAIL` binding (Cloudflare Email Sending) |
| 138 | to `COSTS_ALERT_EMAIL` (`hey@flagon.io`). An empty value sends none. |
| 139 | |
| 140 | ## Schedule |
| 141 | |
| 142 | The daily cron (`17 4 * * *`, `keeper::DAILY`) runs, in order: |
| 143 | |
| 144 | 1. The keeper's measurements (sandbox seconds, app requests and CPU), each |
| 145 | a proposal now, not a direct change. |
| 146 | 2. `costs_daily`: |
| 147 | 1. Read Cloudflare's subscriptions (and with them when the billing cycle |
| 148 | starts), then the bill, the Artifacts events and AI Gateway's |
| 149 | analytics. The bill is read over whole billing cycles, every page |
| 150 | (see [The billing cycle](#the-billing-cycle)), and priced over each |
| 151 | cycle; its days replace what was kept for them. The Artifacts events |
| 152 | and the gateway: the first run reads the last 31 days (GraphQL keeps |
| 153 | 31); later runs the last 4, since Cloudflare restates recent days, or |
| 154 | back to the last day read after a gap. Lines are upserted on |
| 155 | `(day, source, product, meter)`, so a re-read replaces, never adds. |
| 156 | 2. g1t's own counts for the same days (replaced per day). |
| 157 | 3. Snapshot `pending_usage` into `pending_days`. |
| 158 | 4. Reconcile the last 31 days (further back after a gap, or to the |
| 159 | first day of the bill's read) into |
| 160 | `margin_days` and `workspace_costs` |
| 161 | (replaced per day). |
| 162 | 5. Drift over the last 7 days into `cost_drift`. |
| 163 | 6. Unit costs over the last 30 days, proposed to the price book. |
| 164 | 7. Apply price versions whose date has come. |
| 165 | 8. Open, update and close margin alerts; email new ones. |
| 166 | 9. Email owners on the plan about rises to come. |
| 167 | |
| 168 | **Run the analysis now** at the top of sudo's Costs & margin and Bill & pricing pages |
| 169 | (`admin_run_costs`) runs all of step 2 at once, alerts included, with no |
| 170 | need to wait for 04:17 UTC. Running it twice is safe: every step replaces |
| 171 | what it wrote. |
| 172 | |
| 173 | ## Reconciliation math |
| 174 | |
| 175 | Every Cloudflare line goes to one of g1t's products ("buckets") by |
| 176 | `cost_map`: the row for its product with the longest matching meter |
| 177 | prefix, `*` last. A line no row claims goes to `unmapped`. |
| 178 | |
| 179 | | Bucket | Cloudflare | Paid for by (`revenue_map`) | |
| 180 | | --- | --- | --- | |
| 181 | | `sandboxes` | Containers, Durable Objects compute duration | `sandbox`, `self_hosted`, `builds` | |
| 182 | | `deployments` | Workers for Platforms | `deployments` | |
| 183 | | `git` | Artifacts operations (and its events, as counts) | `git` | |
| 184 | | `repo_storage` | Artifacts storage | `storage` | |
| 185 | | `actions_cache` | R2 | `cache` | |
| 186 | | `embeddings` | Workers AI, Vectorize | `context` | |
| 187 | | `security` | (Workers CPU, under `platform`) | `security` | |
| 188 | | `domains` | Cloudflare for SaaS | `domains` | |
| 189 | | `models` | not Cloudflare: AI Gateway's settled cost on the ledger; AI Gateway's own daily total (`ai_gateway_requests`) beside it, to check it | every other task (agent runs). A planning run's ledger task is `plan`, the same as the plan's payments' key, so it is reconciled as `planning` (`margin::PLANNING_KEY`), which has no `revenue_map` row: models. Before 2026-10-08 its model cost landed in `platform`, where Cloudflare's bill is the cost, and was lost | |
| 190 | | `platform` | Workers, D1, KV, Queues, Email, Browser Rendering, other Durable Objects | the plan's price | |
| 191 | |
| 192 | For each day and bucket: |
| 193 | |
| 194 | - **Cloudflare cost** = Σ the bucket's lines' cost, after the included |
| 195 | amounts over the billing cycle (see [The billing cycle](#the-billing-cycle)), |
| 196 | so a cycle inside them costs $0 here as on Cloudflare's Billable usage |
| 197 | page, and the day its total passes one carries the cost. `models` uses the ledger's cost of the |
| 198 | tokens instead; that is paid to the model providers and is not on |
| 199 | Cloudflare's bill. Its "Cloudflare" column is what AI Gateway priced the |
| 200 | same traffic at, which drift compares with the ledger (below); it is |
| 201 | never added to the cost. |
| 202 | - **Own cost** = Σ the ledger's `cost_micros` for the bucket's keys (the |
| 203 | price book's cost when charged), plus month-end deltas. A workspace's own |
| 204 | model provider is no cost to g1t. |
| 205 | - **Value** = what customers were charged at price: `-amount_micros` plus |
| 206 | what the plan's included usage, a trial, the open-source pool or g1t paid. |
| 207 | g1t's own (comped) workspaces are valued at cost plus the margin. |
| 208 | - **Cash** = what workspaces paid with real money: `-amount_micros`, and |
| 209 | the plan's price, from the day payments went live (see "charged without |
| 210 | real money" below). Never tax or card fees: a payment credits the |
| 211 | balance, and `plan_payments`, without them (see [Tax and the card fee](#tax-and-the-card-fee)). |
| 212 | - **Given away** = the part of the cost that went on usage g1t paid for |
| 213 | itself on purpose, by why: |
| 214 | - **comped**: all of a comped workspace's cost, every bucket; |
| 215 | - **free use**: a free period's usage, the overruns g1t covered |
| 216 | (`ledger.given_micros`), and all of a workspace's cost on a day it had |
| 217 | nothing priced (free allowances); |
| 218 | - **trial** and **open-source pool**: what `trial_micros` and |
| 219 | `oss_micros` paid; |
| 220 | - **discount**: what a discount on an account's custom terms took below |
| 221 | cost plus the margin (`ledger.discount_micros`, see |
| 222 | [Margin floor](#margin-floor)). The usage is valued at its price, so a |
| 223 | discounted sale never reads as margin lost; |
| 224 | - **promotional credit** and **goodwill credit**: what credit staff gave |
| 225 | paid for, when it is spent (`given_credit_promotional_micros`, |
| 226 | `given_credit_goodwill_micros`, migration 0038). That usage's charge is |
| 227 | taken out of cash, so it is never money in. A refund is not here: see |
| 228 | [Credits from g1t](#credits-from-g1t); |
| 229 | - **testing resets**: what a workspace's usage cost g1t before staff |
| 230 | reset its billing (`reset_costs`, `given_reset_micros`, migration |
| 231 | 0046). The model calls and Cloudflare usage still happened, so the |
| 232 | reconciliation reads the kept rows back as that workspace's usage on |
| 233 | their days: valued as before, no cash, all of it given. See |
| 234 | [Resetting a test workspace](#resetting-a-test-workspace); |
| 235 | - **charged without real money**: what workspaces were charged, and |
| 236 | plans paid, while payments were not live (Stripe's test mode), or |
| 237 | before the day they went live (`cost_settings.payments_live_since`, |
| 238 | kept the first time the run sees live payments). It brought in no |
| 239 | money, so it is taken out of cash and given (`given_unpaid_micros`, |
| 240 | migration 0052): never money in, never margin, never what a workspace |
| 241 | paid. The plan's included usage counts as money in only from that day |
| 242 | too. |
| 243 | |
| 244 | Otherwise a workspace's day is split by those shares of its value at |
| 245 | price, and the same shares of each of its buckets' cost are given, its |
| 246 | part of running g1t included. The Team plan's included usage is sold: |
| 247 | the plan's price paid for it. Stored on `margin_days` (`given_micros` |
| 248 | and `given_<why>_micros`, `given_discount_micros` from migration 0036) |
| 249 | and `workspace_costs` (`given_micros`). Sudo's Costs & margin page lists |
| 250 | each why by name, testing resets included (`givenResetMicros`). |
| 251 | - **Month-end meters**: a day's figure is that day's `pending_days` |
| 252 | snapshot less the day before's, within a month. Their month-end ledger |
| 253 | entries are left out, so nothing is counted twice. On a 100%-discount |
| 254 | workspace the snapshot's charge is valued and given (comped), never cash: |
| 255 | the month's close takes all of it off (`margin::comped_meter`). |
| 256 | - **Product margin** = (value − cost) / value: a share of the price, so |
| 257 | cost plus 20% is a 16.7% margin. Sudo labels every margin "of price". |
| 258 | - **Sudo's statement** keeps apart: |
| 259 | - **Usage sold**: cash for usage against the cost of the usage buckets |
| 260 | less what was given. Its margin is the headline; at cost plus 20% it |
| 261 | sits near 16.7%. |
| 262 | - **Running g1t**: the plan's price against `platform` less its given |
| 263 | share. |
| 264 | - **Cloudflare subscriptions**: what Cloudflare lists, a month |
| 265 | (`cf_subscriptions`), accrued over the range day by day as each day's |
| 266 | share of its billing cycle (`OverallMargin.subscriptions_micros`); |
| 267 | until a read has worked, `CLOUDFLARE_FIXED_MONTHLY_MICROS`, an |
| 268 | estimate. |
| 269 | - **Not mapped**: billed, charged for by nothing. |
| 270 | - **Given away**: by why. A budget, watched under g1t's own spend, never |
| 271 | shown as a loss. |
| 272 | - **All in**: money in against all of it, with the figure without what |
| 273 | was given beside it. **Who g1t paid** is All in's cost, split into |
| 274 | Cloudflare's usage, Cloudflare's subscriptions over the range, and the |
| 275 | model providers (the ledger's cost); where AI Gateway priced g1t's own |
| 276 | provider traffic at more than a cent apart from that |
| 277 | (`OverallMargin.gateway_cost_micros`, Cloudflare-billed requests left |
| 278 | out), it says so beside it, and the `models` drift says why. |
| 279 | |
| 280 | The overall alert is (Σ cash − (Σ cost − Σ given)) / Σ cash. |
| 281 | - **Quantities**: where a mapping names an `own_meter`, Cloudflare's |
| 282 | billed quantity of those lines (or, without one, Artifacts' operation |
| 283 | events) against g1t's own count. |
| 284 | |
| 285 | **Shared costs to workspaces.** A bucket's cost is shared in proportion |
| 286 | to, first available: Cloudflare's own per-workspace count |
| 287 | (`cloudflare_<bucket>`, today the Artifacts events by repository), g1t's |
| 288 | own count, what its usage cost (so free use carries its own cost), what |
| 289 | each was charged for it. `platform` |
| 290 | and `unmapped` are shared by each workspace's share of all usage that |
| 291 | day. Shares are whole micros that add up to the bill exactly (largest |
| 292 | remainder). On a day no workspace used anything, running g1t has no one to |
| 293 | share it: it stays no one's, and sudo says how much under **Workspaces that |
| 294 | cost most** (`CostsReport.unattributed_micros`), so the workspaces' costs |
| 295 | and it add up to the statement's cost. |
| 296 | |
| 297 | ## Drift (last 7 days) |
| 298 | |
| 299 | | Kind | When | What to do | |
| 300 | | --- | --- | --- | |
| 301 | | Count | g1t's count and Cloudflare's differ by more than the mapping's `drift_percent` (10%) | Find out what Cloudflare counts: compare its events with `own_counts` `artifacts_*` and `cost_operations`. If it counts more (binding reads, `ls-refs`), either change repos' `operation_mapping` so customers are charged for what Cloudflare counts, or leave it and let the per-unit cost rise (below). | |
| 302 | | Cost | Cloudflare charged more than `drift_percent` away from the price book's cost of the same usage, with at least `min_daily_cost` | A price is stale: check the proposals. | |
| 303 | | Cost, on `models` | What AI Gateway priced g1t's own provider traffic at over the 7 days, against the ledger's model cost for the same days (billed to g1t: comped, free and trial use included, a workspace's own provider not) plus the model cost testing resets kept for those days (`reset_costs`), more than the `ai_gateway_requests` mapping's `drift_percent` (10%) apart, with at least `min_daily_cost`. A ledger with none of the gateway's cost is drift too, and so is a gateway that priced nothing against a ledger with at least `min_daily_cost` of model cost (no percentage): that is not agreement. Its detail says why as far as the run could tell: requests logged with no price (add the models' prices), a token Cloudflare refuses for the gateway (give it AI Gateway Read, or fix `AI_GATEWAY_ID`), a gateway the token sees with no requests (calls went around it), or a read that failed | The gateway higher: model calls g1t paid for and charged no one: runs not settled yet (they catch up within the hour), runs with no session, a run started without a billing ticket, or something else on g1t's gateway. The ledger higher: runs that reached a provider without the gateway. The detail adds why the gateway's own figure may be off: prompt-cache read and write tokens (the gateway prices them at its rates for cache tokens, which can lag the provider's; check against the provider's invoice), requests Cloudflare billed itself (unified billing: on Cloudflare's bill, not a provider's), and models with no price. A testing reset in the window is named in the detail: one that kept its cost says how much of the ledger's side it is; one from before resets kept their cost (the audit log has it, `reset_costs` does not) says the gateway's figure includes usage the ledger no longer has, so that part is not a leak, and the day it leaves the 7 days; while such a reset is in the window the `models` leak is not raised. Days are UTC by when a request ran (gateway) and when a charge was entered (ledger), so a run across midnight shifts a little between days; the 7-day sum absorbs it. | |
| 304 | | Unpriced | Over the 7 days, a model in AI Gateway's analytics with tokens and $0 cost, or runs settled with `runs.gateway_note` (the gateway could not price all of a run) | The gateway has no price for a model g1t runs: add it in the gateway (custom cost) or route away from it. Until then those runs are charged no less than the sandbox reported (Claude Code's own price table), never $0 silently. | |
| 305 | | Leak | Cost of at least `min_daily_cost` and nothing charged for it (never for `platform`), or a meter in `unmapped` | Map the meter (below), or decide it is overhead (`platform`). | |
| 306 | |
| 307 | ## Prices: versions, proposals, notice |
| 308 | |
| 309 | - `price_versions` holds every price ever, never edited. `prices` is the |
| 310 | version in force. The daily run applies a version once its |
| 311 | `effective_at` has come, and adds the public `price_changes` record. |
| 312 | Ledger entries made from the price book carry `price_version` (the |
| 313 | version ids, comma-separated), so a past statement is always explained |
| 314 | by the prices of its day. |
| 315 | - Proposals come from the keeper (sandbox seconds, app requests and CPU) |
| 316 | and the reconciler (mappings with `scale_to_own`: today git operations). |
| 317 | For git operations: Cloudflare's rate per its own operation (the median |
| 318 | over charged days of cost ÷ quantity) × (Cloudflare's operations ÷ g1t's) |
| 319 | × 1,000. If Cloudflare counts three for each one g1t counts, the per-1,000 |
| 320 | price triples. At least 1,000 of g1t's operations are needed. |
| 321 | - Decision (`pricing::decide`): under 2% is noise; more than 4× either way |
| 322 | is suspect and waits for staff; within `auto_apply_percent` (25%) it is |
| 323 | applied on its own when `auto_apply` is on; anything else waits. |
| 324 | - Notice: a fall applies at once. A rise applies `notice_days` (14) after |
| 325 | the decision, and for a monthly meter (git, storage, cache, domains, |
| 326 | embeddings, scans) at the start of the month after that, so no month |
| 327 | is charged at two prices. Owners of workspaces on the plan are emailed |
| 328 | once per rise (`price_notices`), and the pricing page lists it with |
| 329 | "takes effect". Rises are never retroactive; margin protection is for |
| 330 | new usage once notice has run. |
| 331 | - A newer measurement before a rise's date replaces its version, with |
| 332 | the new rise's own full notice; the proposal behind the replaced version |
| 333 | is marked `superseded` (it never took effect, and nothing was charged at |
| 334 | it). Sudo says "applied by guardrail, then replaced by a later |
| 335 | measurement". Migration 0049 marks the ones from before: sandbox and |
| 336 | build seconds' rises of 2026-10-07, replaced on 10-08. |
| 337 | - Staff approve or reject in sudo. A rejection needs a note. |
| 338 | - **Price versions** in sudo show each version's cost and price, except |
| 339 | where the cost column is not a cost (`PriceVersion.basis`, |
| 340 | `pricing::basis_of`): the agent rate and security activation are rates |
| 341 | g1t sets (`rate`, no cost shown), and the agent rate's token weights are |
| 342 | multipliers (`weight`, shown as ×0.1). Dates show with their time: a |
| 343 | version from 00:00 UTC is the evening before in the Americas. |
| 344 | |
| 345 | ## Changing a mapping |
| 346 | |
| 347 | In sudo, Costs & margin → Bill & pricing → **Mappings**: Cloudflare's product and meter |
| 348 | prefix (as **Cloudflare's lines** lists them; `*` for the rest of the |
| 349 | product), g1t's product, and optionally: |
| 350 | |
| 351 | - **Price meter**: the price book meter the line measures. |
| 352 | - **Own meter**: g1t's count of the same units (`own_counts.meter`). |
| 353 | - **Scale to g1t's count**: price one of g1t's units at as many of |
| 354 | Cloudflare's as it took (proposals as above). |
| 355 | - **Drift threshold**. |
| 356 | |
| 357 | It applies from the next run; **Run the analysis now** applies it at once. |
| 358 | Every change is in the audit log (`cost_mapping`). |
| 359 | |
| 360 | ## Which raw meters are operations |
| 361 | |
| 362 | There is one mapping, and the repos service owns it: `operation_mapping` |
| 363 | in g1t-repos' database, one row per raw meter with `cost_operations` (how |
| 364 | many operations Cloudflare bills for it) and `billable_operations` (how |
| 365 | many the customer is charged for). Change it with repos' |
| 366 | `set_operation_mapping` RPC (services only), or |
| 367 | `npx wrangler d1 execute g1t-repos --remote` until sudo has a form. A |
| 368 | change applies to counts from then on, never to what was counted. |
| 369 | Billing keeps no mapping of its own: it reads repos' `git_operations` |
| 370 | (already mapped) for what customers are charged, and `artifacts_usage` |
| 371 | (raw counts with the mapping) for `cost_operations`. Migration 0023 drops |
| 372 | the `billable_units` table 0022 made for this, which was never written. |
| 373 | |
| 374 | **Charged at price** (a product's value) is what each day's usage was paid: |
| 375 | charged to a card or credit, or drawn from the plan's included usage, a |
| 376 | trial, a pool or a gift. Usage nothing paid for, as in a free period, is |
| 377 | valued at price (cost plus the margin), since it was given away at its price |
| 378 | rather than sold for nothing; so are g1t's own workspaces. Runs on a |
| 379 | workspace's own model provider have no cost to g1t. Every daily run |
| 380 | reconciles the whole 31-day window from what is already kept, so a change in |
| 381 | how a day is valued reaches every day sudo shows. |
| 382 | |
| 383 | ## Alerts runbook |
| 384 | |
| 385 | | Alert | Raised when | First steps | |
| 386 | | --- | --- | --- | |
| 387 | | Margin under the floor | A product's value against cost under `margin_floor_percent` (10%) for `alert_days` (3) days running, each with at least `min_daily_cost` | Open the product on Costs & margin. Cost up? Check proposals (approve a rise; it waits out the notice). Value down? A mapping or `revenue_map` may have moved. | |
| 388 | | All of g1t under the floor | The same for money in against the cost of what was sold: every cost less what was given away (comped workspaces, free periods, the trial, the pools), which is a budget watched in budget.rs. While less than $1 a day comes in, it says the dollars, not a percentage | Look at which products moved; check `platform` (it has no revenue of its own and grows with traffic). Before launch, with little paid usage, expect it. | |
| 389 | | Leak | Drift of kind leak | Map the meter, or decide it is overhead. | |
| 390 | | Drift | Count drift | See Drift above. Cloudflare's definitions change in beta: ask them in writing ([ARTIFACTS.md](ARTIFACTS.md), §7). | |
| 391 | | Costs more than it pays | A workspace's shared cost over 30 days above what its usage was priced at (`value_micros`, whoever paid: card, trial, gift or included usage) × `anomaly_factor`, at least `anomaly_floor`; not comped workspaces | Shown on Reach out as "Costs more than it pays": its usage is priced below what it costs. Abuse (Abuse & fraud page) or a gap in pricing. Not emailed. A trial or gift paying for usage does not raise it. | |
| 392 | |
| 393 | Alerts close on their own when the condition clears. Open ones are |
| 394 | emailed again weekly. The red bar on every sudo page shows margin, |
| 395 | overall and leak alerts. |
| 396 | |
| 397 | ## Model costs |
| 398 | |
| 399 | Every model call g1t pays for is an agent run's (the `claude` CLI in the |
| 400 | sandbox, `crates/runner`) or a customer's AI Gateway request (a workspace |
| 401 | token with `models:write` at `models.g1t.sh/anthropic` or |
| 402 | `models.g1t.sh/openai/v1`, `gateway.rs`, to Claude on Anthropic or to open |
| 403 | models on Workers AI through the same AI Gateway); the only other model is |
| 404 | Workers AI's embeddings for g1t's own search, which are on Cloudflare's bill |
| 405 | (`embeddings`). How each reaches the ledger: |
| 406 | |
| 407 | | Call | Who pays | Run and session | Ledger cost | Settled to the gateway | |
| 408 | | --- | --- | --- | --- | --- | |
| 409 | | Agent run through the model proxy (`services/models`) on g1t's hosted models | g1t | `runs` row; session `ms_…` in `cf-aig-metadata` | On finish, the sandbox's figure (Claude Code's `total_cost_usd`, at its own price table, cache tokens included) | Yes, every 15 minutes | |
| 410 | | Agent run straight to the gateway (no `MODELS_URL`) | g1t | `runs` row; session `rs_…` in `cf-aig-metadata` (`services/runner` `gatewaySession`) | As above | Yes | |
| 411 | | Agent run with no gateway (`AI_GATEWAY_ID` empty, self-hosting) | g1t's key | `runs` row, no session | The sandbox's figure | No: nothing to settle against | |
| 412 | | Agent run on a workspace's own provider | The workspace | `runs` row, `billed_to = 'workspace'`, session `ms_…` (the proxy counts its tokens by it) | No model cost (none to g1t); the agent rate on `agent_tokens_own`, line `<run>/agent-own` | No; never on g1t's gateway. Closed by the cron's `settle_own_runs`, which charges tokens counted late | |
| 413 | | AI Gateway request on g1t's key | The workspace, from included usage and AI credit (`gateway_admit` refuses at $0, over the limit, or with no plan) | No run; `gateway_requests` row; session `gw_<token>_<YYYYMMDDHH>` in `cf-aig-metadata` (`task: gateway`) | Per request: its tokens at `gateway_models` (the table, migrations 0045 and 0047: list price per million by kind, five-minute and one-hour cache writes apart, and for a model priced by prompt length such as Claude Haiku 5.5 a `threshold` above which the whole request is at the `over_` prices) plus the `gateway_models` meter's markup (0 in beta); a `usage` line with task `gateway`, reference the request id, quantity 1 | No, not yet: the session tag is there for it. **Cost** drift on `models` compares the gateway's total with these lines too. Requests billed other than by tokens (fast mode, `inference_geo`, fallbacks, server tools, containers) are refused by the proxy | |
| 414 | | AI Gateway request on a workspace's own provider (any model connection whose `gateway_models` takes the model) | The workspace's provider | `gateway_requests` row, `own_key = 1`, `provider` and `connection` | None | No; never on g1t's gateway | |
| 415 | | A sandbox that died before reporting | g1t | as its route | Charged from the gateway when settled | Yes | |
| 416 | | Embeddings (indexing) | g1t | none (Workers AI) | Month-end `context` meter | No: Cloudflare's bill, `embeddings` bucket | |
| 417 | | Embeddings (queries, search and agent context) | g1t | none | None: not charged, by design | No: in Cloudflare's `embeddings` line, shared out | |
| 418 | |
| 419 | **Settling.** A run's charge is corrected to what AI Gateway priced its |
| 420 | session's requests at (`settled_cost` in `keeper.rs`). The gateway's |
| 421 | figure is trusted in full: it is not held to the $100 cap on a sandbox's |
| 422 | own report. It is never taken below what the sandbox reported when it |
| 423 | cannot be the whole cost: a request with tokens and no cost (a model the |
| 424 | gateway has no price for) or more logs than are read (2,000). Such a run |
| 425 | keeps `runs.gateway_note`, its correction says why, and it raises the |
| 426 | **Unpriced** drift. For agent runs g1t keeps no token rates of its own: |
| 427 | the first figure is Claude Code's, the final one the gateway's. AI Gateway |
| 428 | requests are the exception: they are charged from `gateway_models` (the |
| 429 | model catalogue, below), which has to follow the provider's price list by |
| 430 | hand until they are settled like runs. It is not part of the price book's |
| 431 | `price_versions`: a new model's prices are confirmed when staff approve it |
| 432 | in sudo, and a changed price on a model already offered is a migration that |
| 433 | updates the row and its `updated_at` (as 0047 did for Sonnet 5.5's cache |
| 434 | reads). The `gateway_models` meter's markup is the only price-book number |
| 435 | on it. Open |
| 436 | models need `WORKERS_AI_TOKEN` (a Cloudflare API token with Workers AI on |
| 437 | g1t's account) on the model proxy; without it, and without |
| 438 | `AI_GATEWAY_TOKEN` holding that permission, they are refused with `503`. |
| 439 | |
| 440 | **The daily total.** AI Gateway's analytics for the day (above) against |
| 441 | the ledger's model cost is the check that nothing slips past: a model call |
| 442 | with no run, or a run never settled, shows as **Cost** drift on `models`. |
| 443 | The gateway's per-request `cost` is its estimate from its own price list: |
| 444 | it can be off for prompt-cache tokens, for requests Cloudflare bills |
| 445 | itself, and for models it has no price for. The drift's detail says when |
| 446 | any of those were in the window; the provider's invoice is the last word. |
| 447 | |
| 448 | ### Margin floor |
| 449 | |
| 450 | A sold charge is cost × (1 + `MARGIN_PERCENT`), rounded up (`margin_on`; |
| 451 | `charge_micros` for a sandbox's own report). Terms change it only as |
| 452 | follows (`Terms::discounted`, `Billing::charged`): |
| 453 | |
| 454 | - **Standard**: charged in full. |
| 455 | - **A 100% discount** (what was "comped"; see [Discounts](#discounts)), |
| 456 | `FREE_WHILE_BUILDING`, the plan's included usage, the trial, |
| 457 | the open-source pool, and overruns g1t covers: given, and counted by why |
| 458 | (above). |
| 459 | - **Custom, with a discount**: the discount comes off, and what it took |
| 460 | below cost plus the margin is written on the entry as |
| 461 | `ledger.discount_micros` and counted as given (**discount**), so the sale |
| 462 | is valued at its price and charged plus given is never under cost plus the |
| 463 | margin. On a settlement correction it moves with the charge (less than |
| 464 | nothing when the charge comes down). |
| 465 | - **Goodwill credits** (overages) are separate, given by staff on purpose: |
| 466 | their margin part first, the cost only up to the cap, each audited. |
| 467 | |
| 468 | Every usage path goes through this: `finish_run`, settling, sandbox time, |
| 469 | features and builds (`charge_feature`), and the month-end meters. |
| 470 | |
| 471 | ## The model catalogue |
| 472 | |
| 473 | Every model g1t can use is one row of `gateway_models` (migrations 0045, |
| 474 | 0047 and `0048_model_catalogue.sql`; code in `catalogue.rs`): the agents' |
| 475 | tiers, the AI Gateway's Claude and open models, and the embeddings model. |
| 476 | Billing keeps it because billing owns prices: the gateway charges from the |
| 477 | same row, so there is one price per model, not two that drift. Page: sudo |
| 478 | **Agents & models** (`/agents`). |
| 479 | |
| 480 | | Column | What | |
| 481 | | --- | --- | |
| 482 | | `model`, `name`, `provider`, `kind` | The provider's id, the name people see, `anthropic` or `workers-ai`, `chat` or `embeddings` | |
| 483 | | `aliases` | Other ids the provider lists it by, comma separated (a dated id such as `claude-haiku-4-5-20251001`) | |
| 484 | | `family`, `tier_hint` | `haiku`, `sonnet`, `opus`, `fable` (or a Workers AI author); the agent tier it suits: `small`, `large`, `frontier` | |
| 485 | | `context_window`, `max_output`, `capabilities`, `dimensions` | From the provider's list where it gives them: `effort`, `thinking`, `tools`, `vision`, `embeddings`; an embeddings model's vector length | |
| 486 | | Prices | Per million tokens in millionths: input, output, cache read, five-minute and hour-long cache writes, and for a model priced by prompt length the `threshold` and `over_` prices | |
| 487 | | `status` | `available` (routed to and offered), `new` (found, not approved), `deprecated` (the provider stopped listing it), `retired` (staff took it out) | |
| 488 | | `priced` | 1 when its prices are known | |
| 489 | | `source`, `first_seen_at`, `last_seen_at`, `missing_since`, `approved_by`, `approved_at`, `note` | Where it came from (`discovered` or `staff`) and its history | |
| 490 | |
| 491 | What each status allows: |
| 492 | |
| 493 | | Status | Default for a purpose | Offered on the AI Gateway | Charged | |
| 494 | | --- | --- | --- | --- | |
| 495 | | `available`, priced | Yes | Yes | Yes | |
| 496 | | `new`, or unpriced | No | No: refused before it reaches a provider | No | |
| 497 | | `deprecated` | No: a default that chose it falls back | Yes, to whoever names it | Yes | |
| 498 | | `retired` | No: a default that chose it falls back | No | No | |
| 499 | |
| 500 | ### Discovery |
| 501 | |
| 502 | The models service lists each provider once a day (`29 5 * * *`, after |
| 503 | billing's daily run) and whenever staff press **Check for new models** |
| 504 | (`services/models/src/discover.ts`, through its `Discovery` entrypoint, |
| 505 | which only sudo binds). Listing models is free; nothing calls a model. |
| 506 | |
| 507 | | Provider | How it is listed | Credentials (on g1t-models) | |
| 508 | | --- | --- | --- | |
| 509 | | Anthropic | `GET /v1/models` through g1t's AI Gateway (`…/anthropic/v1/models`, tagged `task: discovery`), or straight to Anthropic with g1t's key when there is no gateway | `AI_GATEWAY_TOKEN` (the gateway holds Anthropic's key), or `ANTHROPIC_API_KEY` | |
| 510 | | Workers AI | `GET /accounts/{account}/ai/models/search` | `WORKERS_AI_TOKEN` (Workers AI Read), else `AI_GATEWAY_TOKEN` | |
| 511 | |
| 512 | Each provider's list goes to billing's `record_discovery`, which compares |
| 513 | it with the catalogue: |
| 514 | |
| 515 | - **An id it has never seen** is added as `new`. Chat and embeddings |
| 516 | models only. Anthropic models are priced from the price table in |
| 517 | `catalogue.rs` (`ANTHROPIC_PRICES`: Anthropic's list prices by model, a |
| 518 | dated id priced as its model) when it has them; Workers AI models from |
| 519 | the price their listing gives, with cached tokens at the input price. |
| 520 | Anything else is added unpriced. Its family and tier hint come from its |
| 521 | id (`claude-haiku-*` is fast, `claude-sonnet-*` standard, |
| 522 | `claude-opus-*` and `claude-fable-*` most capable). |
| 523 | - **A dated id of a model it has** (`claude-sonnet-5-5-20261001`) is that |
| 524 | model: the id is added to its aliases. |
| 525 | - **A model it has that is listed** gets `last_seen_at`, and its context |
| 526 | window, output limit and capabilities from the list. |
| 527 | - **A model it has that is not listed** (available or new) becomes |
| 528 | `deprecated`, with `missing_since`. Listed again, it goes back to |
| 529 | `available` if it was ever approved, else to `new`. |
| 530 | - **An empty list or a failed one** changes nothing: it is recorded as a |
| 531 | failed check with the provider's answer (never a key). |
| 532 | |
| 533 | Every check is kept 90 days in `model_checks` and shown on the page. When a |
| 534 | check adds, deprecates or restores anything, it is in the audit log |
| 535 | (`models_discovered`, as `schedule` or the staff member) and staff are |
| 536 | emailed at `COSTS_ALERT_EMAIL` with a link to Agents & models. |
| 537 | |
| 538 | When Anthropic publishes a new model's price, add a row to |
| 539 | `ANTHROPIC_PRICES`, so the next one of its kind arrives priced. Until then |
| 540 | staff enter the prices when they approve it. |
| 541 | |
| 542 | ### Approving, retiring and restoring |
| 543 | |
| 544 | On Agents & models, **New models** lists every `new` model with its prices |
| 545 | filled in where they are known. To approve one: |
| 546 | |
| 547 | 1. Check the name people see and the tier it suits. |
| 548 | 2. Check or enter its prices per million tokens against the provider's |
| 549 | price page: input, output, cache read, cache writes (five-minute and |
| 550 | hour-long; an hour-long price left empty is the five-minute one), and |
| 551 | under **Priced by prompt length** the threshold and the prices above it. |
| 552 | 3. Say why (for example where the prices came from), and **Approve** |
| 553 | (`admin_decide_model`, `approve`). |
| 554 | |
| 555 | It is `available` at once: the AI Gateway offers it within five minutes |
| 556 | (the proxy keeps the catalogue that long) and it can be chosen as a |
| 557 | default. **Retire** takes a model out of routing and the gateway; any |
| 558 | default that chose it falls back to the next suitable model until staff |
| 559 | choose another, and the audit line names those defaults. **Restore** puts |
| 560 | a retired or deprecated model back: `available` if it was ever approved, |
| 561 | else `new`. Each needs a reason and is in the audit log (`model_approved`, |
| 562 | `model_retired`, `model_restored`). |
| 563 | |
| 564 | ### Defaults |
| 565 | |
| 566 | `model_defaults` holds staff's choice per purpose, each with when, who and |
| 567 | why (`admin_set_model_default`; the audit log, `model_default`, has the old |
| 568 | value, the new one and why): |
| 569 | |
| 570 | | Purpose | What it chooses | Read by | |
| 571 | | --- | --- | --- | |
| 572 | | `tier_small`, `tier_large`, `tier_frontier` | The model behind Auto's fast, standard and most capable tiers | The runner | |
| 573 | | `background` | The harness's own small tasks in every run on g1t's tiers (`ANTHROPIC_SMALL_FAST_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`) | The runner | |
| 574 | | `gateway_first` | The Claude listed first by `GET /openai/v1/models` | Billing's `gateway_models` | |
| 575 | | `job_implement`, `job_revise`, `job_answer`, `job_review`, `job_update`, `job_plan` | Each kind of job's starting tier (`small`, `large`, `frontier`; a review also `change`, sized by its change) and effort (`low` to `max`, or none for the harness's own) | The runner | |
| 576 | |
| 577 | A model purpose takes only an available, priced Claude chat model (the |
| 578 | harness speaks Anthropic's API). The migration seeded each with what |
| 579 | `AGENT_ROUTING` had. |
| 580 | |
| 581 | Before a default is saved, sudo shows it beside the current one with what |
| 582 | a **typical run** would cost on each: 40 requests of 2,000 input, 1,500 |
| 583 | output, 45,000 cache-read and 4,000 cache-write tokens, each request priced |
| 584 | on its own at the catalogue's prices (`catalogue::TYPICAL`; on 2026-10-08, |
| 585 | $0.076 on Claude Haiku 5.5, $1.34 on Sonnet 5.5, $2.68 on Opus 5.5). It is |
| 586 | an estimate for comparing models, never a charge. |
| 587 | |
| 588 | **How the runner reads them.** `model_defaults` (the RPC) returns each |
| 589 | purpose's model as it applies now, with its prices and capabilities, and |
| 590 | each job's tier and effort. The runner reads it at most once a minute per |
| 591 | isolate and puts it over `AGENT_ROUTING` (`withDefaults` in |
| 592 | `services/runner/src/model-env.ts`), so a change reaches runs within a |
| 593 | minute. When billing cannot be read, the runner uses `AGENT_ROUTING` (and |
| 594 | `DEFAULT_ROUTING` under it) alone and asks again ten seconds later. The |
| 595 | labels, change sizes, `frontierAfter` and learning always come from |
| 596 | `AGENT_ROUTING`. Effort is not sent on a model whose catalogue entry lacks |
| 597 | `effort` (Claude Haiku 4.5). |
| 598 | |
| 599 | **Never a retired model.** A chosen model that is deprecated, retired or |
| 600 | unpriced is not handed out: the purpose falls back to the first available, |
| 601 | priced Claude with the same tier hint (any Claude for `gateway_first`), in |
| 602 | the catalogue's order, with a sentence such as *Claude Haiku 5.5 is |
| 603 | retired; using Claude Haiku 4.5 instead.* The runner adds that sentence to |
| 604 | the run's reason line, and sudo shows it beside the default. With no model |
| 605 | left for a purpose, the runner keeps `AGENT_ROUTING`'s. |
| 606 | |
| 607 | **Not a default:** the context hub's embeddings model |
| 608 | (`@cf/baai/bge-base-en-v1.5`, in `services/context`). Its vectors are |
| 609 | only comparable with others from the same model, so changing it means a |
| 610 | new index, rebuilt; it is pinned in code, and listed in the catalogue with |
| 611 | its price. No other g1t service calls a model. |
| 612 | |
| 613 | Customers never choose among these: they keep **Auto**, or pin a tier per |
| 614 | kind of work, and nothing customer-facing names the catalogue. |
| 615 | |
| 616 | ## Discounts |
| 617 | |
| 618 | An account's terms are standard, or custom: a **discount** from 1 to 100%, |
| 619 | a limit of its own, or both, with a reason (the terms' note) and an |
| 620 | optional end date. What used to be "comped" is a **100% discount** |
| 621 | (`Terms::full_discount`; migration `0039_discounts_not_comped.sql` moved |
| 622 | every `comped` row to `custom` at 100%, and code reads a leftover `comped` |
| 623 | row as 100%). In SQL, `sales::FULL_DISCOUNT_SQL`. |
| 624 | |
| 625 | - **Charging.** Every charge records what the discount took off it |
| 626 | (`ledger.discount_micros`), 100% included: the entry is charged nothing |
| 627 | and the discount is its whole price. Migration 0039 backfilled the |
| 628 | discount on a 100%-discounted workspace's earlier entries that were |
| 629 | charged nothing and paid by nothing, at cost plus 20%. |
| 630 | - **What a 100% discount still does as "comped" did.** The plan is on |
| 631 | without its price (`PlanKind::Internal`), trust is `internal` (no limit |
| 632 | on unpaid usage), nothing is invoiced or closed, and g1t's own spend on |
| 633 | it is held to the monthly budget (the terms' limit, at cost; see |
| 634 | [Spend caps](#spend-caps)). |
| 635 | - **The statement and Usage.** The customer sees every usage line at its |
| 636 | price (`StatementLine.price_micros`: charged, plus what paid for it, plus |
| 637 | the discount), the discount per day or project and in the totals |
| 638 | (`StatementTotals.price_micros`, `discount_micros`, `discount_percent`), |
| 639 | and the CSV has price and discount columns. The Usage page measures at |
| 640 | price for a discounted account (`Usage.discount_micros`, |
| 641 | `discount_percent`). |
| 642 | - **Margin.** A 100% discount's usage is given away as before, in the |
| 643 | bucket still named `comped` (`given_comped_micros`); sudo calls it |
| 644 | **100% discounts**. A partial discount's part below cost plus the margin |
| 645 | is `given_discount_micros` (**partial discounts**). Both are kept apart |
| 646 | from margin on what was sold. |
| 647 | - **sudo.** The workspace's **Terms** form takes a discount (None, 25%, |
| 648 | 50%, 100%, or Custom, a whole percent; the custom field shows by CSS |
| 649 | alone), a limit, an end date and the reason. Badges and filters say |
| 650 | *100% discount* or *N% off*. Each change is audited (`terms`), such as |
| 651 | `standard → 100% discount, monthly budget $150.00: g1t's own`. |
| 652 | |
| 653 | ## Credits from g1t |
| 654 | |
| 655 | Staff give a workspace credit from sudo; the code is |
| 656 | `services/billing/src/grants.rs`, the tables `credit_grants` and |
| 657 | `ledger.credit_kind` (migration `0038_staff_credits.sql`). |
| 658 | |
| 659 | ### Giving credit |
| 660 | |
| 661 | sudo → the workspace (or an enterprise, choosing one of its workspaces) → |
| 662 | **Give credit**: |
| 663 | |
| 664 | 1. **Amount**: $10, $20, $25, $50, $100, or **Custom** (up to $10,000). |
| 665 | Up to $100 it is one step; over $100, type the workspace's slug as well. |
| 666 | 2. **Kind**: promotional (a welcome, a referral, an event), goodwill (an |
| 667 | apology), or refund (money back for something that went wrong: say what |
| 668 | it refunds and, optionally, the day). |
| 669 | 3. **Expires**: never, 30, 90 or 365 days, or the end of a chosen day |
| 670 | (UTC). A refund never expires. |
| 671 | 4. **Note**: required. It is on the statement and in the owners' email. |
| 672 | |
| 673 | The form needs no JavaScript: the fields for one choice (the custom amount, |
| 674 | a refund's details, the expiry date) show by CSS alone, and all show where |
| 675 | `:has()` is not supported. `admin_credit` checks everything again. |
| 676 | |
| 677 | A grant is a `crd_…` ledger line (kind `top_up`, so never a payment) with |
| 678 | `credit_kind`, and a `credit_grants` row. The balance rises at once. The |
| 679 | owners are emailed through identity's `notify_owners` (the same path as |
| 680 | limit notices). It is audited as `credit`. The Overages queue's one-click |
| 681 | goodwill credit is a grant too, of kind goodwill. |
| 682 | |
| 683 | The inbox is not told: its items are threads on a repository, built from |
| 684 | events, and a credit is a workspace's. That needs a workspace-level inbox |
| 685 | thread first. |
| 686 | |
| 687 | ### How it is spent |
| 688 | |
| 689 | Credit is spent before anything prepaid, the soonest-expiring grant first |
| 690 | (never-expiring last, then the oldest). Given while the workspace owes, it |
| 691 | pays what is owed first, the most recent usage first. What each grant paid |
| 692 | for is never stored: `grants::replay` works it out from the ledger in order, |
| 693 | so the charge paths do not know about credit and the answer is always what |
| 694 | the ledger says. A charge that comes down (a settled run) gives back to |
| 695 | the grant that paid last, while it can still be spent. |
| 696 | |
| 697 | ### Expiry and revoking |
| 698 | |
| 699 | - **Expiry.** The daily run (`expire_credits`, before the reconciliation) |
| 700 | closes grants past `expires_at` and enters what was left as a negative |
| 701 | `crd…_expired` line; audited as `credit_expired`. A grant past its expiry |
| 702 | pays for nothing even before the run. |
| 703 | - **Revoke.** sudo → the workspace's **Credits** (or **Credits & refunds**) |
| 704 | → **Revoke unused**, with why (`admin_revoke_credit`): what is left, as a |
| 705 | `crd…_revoked` line, audited as `credit_revoked`. What was spent stays |
| 706 | spent. |
| 707 | |
| 708 | Neither takes the balance below zero: at most the balance, if a refunded |
| 709 | payment left less there than the credit. |
| 710 | |
| 711 | ### How margin treats them |
| 712 | |
| 713 | | Kind | When spent | On the day it was given | |
| 714 | | --- | --- | --- | |
| 715 | | Promotional | The usage is valued at its price, its charge comes out of cash and is given (`given_credit_promotional_micros`) | Nothing | |
| 716 | | Goodwill | The same, as `given_credit_goodwill_micros` | Nothing | |
| 717 | | Refund | Paid for: cash, as any usage | Its amount (less what was revoked) comes off cash on the day it refunds, shared over that day's paid usage | |
| 718 | |
| 719 | A refund gives back money already collected, so counting it as given would |
| 720 | make it look like a budget g1t chose to spend. Taking it off cash for the |
| 721 | day it refunds says that day's sale was worth less, and counting what it |
| 722 | later pays for as cash keeps money in equal to what was collected. The |
| 723 | refund's day is clamped to the last 30 days, the days the reconciliation |
| 724 | recomputes; an older one lands on the oldest. Refunds never expire, so |
| 725 | cash taken back is never stranded. |
| 726 | |
| 727 | What credit paid of a month-end meter (storage, git, scans) is its own |
| 728 | row on the day it was charged, since those meters are reconciled from |
| 729 | snapshots. Sudo's Costs & margin lists promotional and goodwill credit |
| 730 | under **Given away**, and below the statement the range's credits given, |
| 731 | spent, and refunded. **Credits & refunds** (`/credits`, `admin_credits`) |
| 732 | lists every grant (by kind, month, staff and workspace) and the last 12 |
| 733 | months by kind: given, spent, expired, revoked. |
| 734 | |
| 735 | ### Purchased and scoped credit (prepaid AI) |
| 736 | |
| 737 | `credit_grants` also has `scope` (`all`, or `models`: model usage only, |
| 738 | `grants::is_model_usage`, which includes the agent rate) and `source` |
| 739 | (`staff`, `purchase`, `promo_code`, `upgrade`), and `CreditKind::Purchased`. |
| 740 | Spending takes credit scoped to models first, then the soonest-expiring. A |
| 741 | grant scoped to models given while the workspace owes pays only what models |
| 742 | owed, never other usage (`replay`). Purchased credit is money paid in: its |
| 743 | ledger line is a payment (Stripe's id, never `crd…`, `credit_kind` |
| 744 | `purchased`, statement kind *AI credit*), and the usage it pays for stays |
| 745 | money in, never given. Staff cannot give it (`admin_credit` refuses the |
| 746 | kind). Code: `services/billing/src/ai.rs`; migration `0040_ai_credit.sql`. |
| 747 | |
| 748 | - **Buying.** `buy_ai_credit` opens Stripe Checkout (payment mode, $10 to |
| 749 | $1,000, a second line *Card processing fee* when the `card_fee` cost |
| 750 | setting is on, `setup_future_usage=off_session`), recorded in `checkouts` |
| 751 | with `feature = 'ai_credit'`, `amount_cents` the credit and `fee_cents` |
| 752 | the fee. The credit is entered by whichever comes first, the person coming |
| 753 | back (`confirm_ai_credit`, `?ai_credit=cs_…`) or |
| 754 | `checkout.session.completed`: both claim the row `open → paid`, the |
| 755 | grant's id is the session's id (`INSERT OR IGNORE`) and the ledger's |
| 756 | reference is unique, so a payment is credited exactly once. Expires 365 |
| 757 | days after purchase (the daily `expire_credits`). |
| 758 | - **Owed.** AI credit props up the balance but is money only for models, so |
| 759 | what is owed is `max(0, AI credit left − balance)` (`owed_with`; at a |
| 760 | month's close, `models_left_before` the month's start). |
| 761 | - **Auto-reload.** `ai_reload` (settings; off by default) and `ai_reloads` |
| 762 | (one row per attempt). Each cron run (and a run that would be refused) |
| 763 | calls `reload_now`: below the threshold, it charges the customer's default |
| 764 | payment method off-session for the target less the balance (whole |
| 765 | dollars, at least $10, within the month's maximum), with the idempotency |
| 766 | key `reload/<workspace>/<YYYY-MM>/<n>` (a retry after a crash is the same |
| 767 | PaymentIntent), and grants purchased credit with the PaymentIntent's id. A |
| 768 | decline or a payment needing the person turns auto-reload off |
| 769 | (`failed_at`, `error`), emails the owners and audits `ai_reload_failed`. |
| 770 | - **At $0.** `start_run` on g1t's models refuses with `payment_required` |
| 771 | when the workspace is on the paid plan (not a 100% discount, not an |
| 772 | enterprise), its included usage is used, and AI credit is $0 or less. |
| 773 | - **Upgrade credit.** The first time a plan subscription is recorded active |
| 774 | (`features::record`), $5 of promotional credit scoped to models, id |
| 775 | `crd_upgrade_<workspace>`, expiring in a year: given, never revenue. Never |
| 776 | for a workspace with a 100% discount. |
| 777 | |
| 778 | ### The agent rate and models' markup |
| 779 | |
| 780 | Price-book meters (migration 0040, each with versions and a public change): |
| 781 | `agent_models` (per provider dollar; markup 20% until 2026-10-08, then 0, |
| 782 | a fall applied at once), `agent_tokens` ($0 until 2026-10-22, then $0.25 a |
| 783 | million tokens: a rise, after the 14 days' notice, emailed to owners on the |
| 784 | plan by `tell_owners_of_rises`), `gateway_models` (markup 0 during beta), |
| 785 | `card_fee_percent` (29,000 micros per dollar) and `card_fee_fixed` |
| 786 | (300,000). Changing any is a price-book change, never a deploy. `finish_run` |
| 787 | and `settle` charge models at `agent_models`' markup; `charge_agent_rate` |
| 788 | charges the weighted tokens of the run's session since it was last charged |
| 789 | (`runs.agent_tokens`, the weighted tokens charged so far, claimed with a |
| 790 | compare-and-set), on a line `<run>/agent` (later `<run>/agent/<tokens>`), |
| 791 | with `quantity` the weighted tokens. What it counts is the more of what |
| 792 | `token_usage` holds for the session and what the sandbox reported with its |
| 793 | cost (`finish_run`'s `tokens`, from Claude Code's closing `usage`), each |
| 794 | weighted by kind. **Card fee switch:** sudo → Costs → Guardrails → *Card fee |
| 795 | on card payments* (`cost_settings.card_fee`, `on`/`off`, on by default). It |
| 796 | covers every card payment now, not only AI credit: see |
| 797 | [Tax and the card fee](#tax-and-the-card-fee). |
| 798 | |
| 799 | **On a workspace's own model key** (migration `0041_agent_rate_own_key.sql`): |
| 800 | the run keeps its model session (`runs.session_id`, `ms_…`) so the proxy's |
| 801 | counts reach it, and the agent rate is charged at `agent_tokens_own` ($0 until |
| 802 | 2026-10-22, then $0.25 a million, a rise from nothing with its notice), on |
| 803 | `<run>/agent-own` (later `<run>/agent-own/<tokens>`), `billed_to = 'g1t'` |
| 804 | (g1t's own charge: it counts toward limits and spend), named *Agent rate, |
| 805 | your own model key* on Usage and the statement. The model is never charged. |
| 806 | `settle_runs` skips these runs (nothing on g1t's gateway); the cron's |
| 807 | `settle_own_runs` closes them 5 minutes after they finish (3 hours after |
| 808 | they start, for a sandbox that never reported) and charges tokens counted |
| 809 | late. Runs from before have no session and are never charged the rate. |
| 810 | |
| 811 | ### The agent rate's token weights |
| 812 | |
| 813 | How much each kind of token counts toward the agent rate, on g1t's models |
| 814 | and own keys alike, is four price-book meters (migration |
| 815 | `0042_agent_rate_weights.sql`): `agent_token_weight_input`, `_output`, |
| 816 | `_cache_read` and `_cache_write`, each a weight in millionths in |
| 817 | `cost_micros` (1,000,000 counts a token once). They started at 1, which is |
| 818 | what the rate always counted; since 2026-10-08 cache reads count a tenth |
| 819 | (100,000; migration `0044_cache_reads_count_a_tenth.sql`), as model providers |
| 820 | price them. Input, output and cache writes count once. A cached agent run reads most of its context from |
| 821 | cache (about 90% of its tokens on a typical Sonnet implement run), so the |
| 822 | cache-read weight is the lever: at 1 the rate adds about 44% to such a run's |
| 823 | model cost; at 0.1, far less. |
| 824 | |
| 825 | To change a weight (cache reads went to a tenth this way): |
| 826 | |
| 827 | 1. Add the version, effective at once (a lower weight is a fall): |
| 828 | |
| 829 | ```sql |
| 830 | INSERT INTO price_versions (id, meter, version, cost_micros, markup_percent, effective_at, reason, created_by, created_at) |
| 831 | VALUES ('pv_agent_token_weight_cache_read_2', 'agent_token_weight_cache_read', 2, 100000, 0, |
| 832 | '2026-10-08T00:00:00Z', 'Cache reads count a tenth toward the agent rate', 'staff', '2026-10-08T00:00:00Z'); |
| 833 | ``` |
| 834 | |
| 835 | in a migration, or with `npx wrangler d1 execute g1t-billing --remote` |
| 836 | until sudo has a form. |
| 837 | 2. The daily run applies it once `effective_at` has come and writes the |
| 838 | public `price_changes` record (**Run the analysis now** applies it at |
| 839 | once). Raising a weight later is a rise: give it an `effective_at` 14 |
| 840 | days out, and owners on the plan are emailed. |
| 841 | 3. Check `/pricing`: the agent rate's row lists the weights, and Usage's |
| 842 | agent-rate lines name them. |
| 843 | |
| 844 | `weighted` (`ai.rs`) rounds down to a whole token; a weight is never below 0. |
| 845 | |
| 846 | ### Budgets |
| 847 | |
| 848 | The owners' spend limit is the budget. `limits.alert_levels` (comma |
| 849 | separated, default every level), `limits.pause_at_limit` (default 1; off, |
| 850 | 100% is a warning, never a stop; the trust ceiling still stops work) and |
| 851 | `limits.budget_webhook` (an https address, not g1t's; posted once per alert |
| 852 | level a month by `warn_limits`). `set_budget` sets them, with `keepLimit` |
| 853 | to leave the limit itself alone. A free workspace (trust `new`) has no |
| 854 | spend limit to set: `set_spend_limit` and `set_budget` say so. |
| 855 | |
| 856 | ### Earlier credits |
| 857 | |
| 858 | Migration 0038 makes every earlier `Credit from g1t:` line a goodwill |
| 859 | grant with no expiry: the old form asked for "a refund or goodwill" with |
| 860 | no way to tell them apart, and goodwill never reads as money in. |
| 861 | |
| 862 | ## Token usage |
| 863 | |
| 864 | The model proxy (`services/models`) reads Anthropic's `usage` from every |
| 865 | `/v1/messages` answer, streamed or whole, on g1t's models and on a |
| 866 | workspace's own provider alike (OpenAI-shaped providers are translated |
| 867 | first). Count-tokens requests are not answers and are skipped. After the |
| 868 | answer, it calls `record_tokens`, which adds input, output, cache reads and |
| 869 | cache writes to one row per day, workspace, person, session and model in |
| 870 | `token_usage` (migration `0030_token_usage.sql`). The person is who the run |
| 871 | was for, from the model session's `requested_by`; never g1t's agent. A |
| 872 | report that fails is dropped and never affects the answer. |
| 873 | |
| 874 | `token_usage` reads a window (42 days by default, 366 at most) for the |
| 875 | workspace or one person: totals, every day's tokens and the active days, |
| 876 | with `costMicros` the window's run charges from the ledger, measured as |
| 877 | `usage` measures them. Usage's report also lists tokens by model |
| 878 | (`UsageReport.models`). The agent rate is charged on these counts (above); |
| 879 | a run's model is still priced from AI Gateway's logs, never from them. |
| 880 | |
| 881 | ## Tables (migration `0022_costs_and_margin.sql`) |
| 882 | |
| 883 | `cost_lines`, `cost_map`, `revenue_map`, `own_counts`, |
| 884 | `pending_days`, `margin_days`, `workspace_costs`, `cost_drift`, |
| 885 | `margin_alerts`, `price_versions` (seeded with every current price as |
| 886 | version 1), `price_proposals`, `price_notices`, `cost_settings` (the |
| 887 | guardrails, seeded), the `actions_cache` price, and `ledger.price_version`. |
| 888 | Every create is `IF NOT EXISTS` and every seed `INSERT OR IGNORE`; the one |
| 889 | `ALTER` is applied once by D1's migration tracking. Migration |
| 890 | `0023_one_operation_mapping.sql` drops `billable_units` (see above). |
| 891 | Migration `0036_model_costs_in_full.sql` adds `ledger.discount_micros`, |
| 892 | `margin_days.given_discount_micros`, `runs.gateway_note` and the |
| 893 | `ai_gateway_requests` → `models` mapping. Migration |
| 894 | `0038_staff_credits.sql` adds `credit_grants`, `ledger.credit_kind` and |
| 895 | `margin_days.given_credit_{promotional,goodwill}_micros`, and backfills |
| 896 | earlier credits (see [Credits from g1t](#credits-from-g1t)). Migration |
| 897 | `0046_reset_costs.sql` adds `reset_costs` and `margin_days.given_reset_micros` |
| 898 | (see [Resetting a test workspace](#resetting-a-test-workspace)). Migration |
| 899 | `0052_cloudflare_cycle.sql` adds `cost_lines.billed_usd`, |
| 900 | `billable_quantity` and `basis`, `cf_subscriptions.cycle_start`, |
| 901 | `cost_reads`, `margin_days.given_unpaid_micros` and the |
| 902 | `payments_live_since` setting (see [The billing cycle](#the-billing-cycle)). |
| 903 | |
| 904 | ## Spend caps |
| 905 | |
| 906 | Two caps keep what g1t pays for itself bounded while billing takes no |
| 907 | real money. Both are measured at **cost** (what Cloudflare and the model |
| 908 | providers charge g1t), never at price. Code: `services/billing/src/budget.rs`. |
| 909 | Page: sudo **Costs & margin** → **g1t's own spend** (`/costs#spend`). |
| 910 | |
| 911 | ### What counts as g1t's own spend |
| 912 | |
| 913 | Every charge that settles (an agent run's model cost from `finish_run` or |
| 914 | AI Gateway's settlement, sandbox time from `record_sandbox`, a build from |
| 915 | `charge_feature`) is split by what paid for it and g1t's part is added to |
| 916 | `g1t_spend` (day, bucket, billing account): |
| 917 | |
| 918 | | Bucket | What | |
| 919 | | --- | --- | |
| 920 | | `comped` | All of a comped account's work (flagon-io) | |
| 921 | | `trial` | The trial credit's share | |
| 922 | | `oss` | The open-source pool's share | |
| 923 | | `given` | A free workspace's overrun past its last bit of trial | |
| 924 | | `unpaid` | Charged, but with no real money behind it: Stripe's test key, or `FREE_WHILE_BUILDING` | |
| 925 | |
| 926 | The plan's included usage and on-demand charges count as revenue only |
| 927 | with live payments; in test mode they are `unpaid`, at what the usage cost |
| 928 | g1t, never what was charged. A workspace's own |
| 929 | model provider costs g1t nothing and is not counted. Month-end meters |
| 930 | (git, storage, scans, embeddings, the cache) are not counted here; the |
| 931 | daily reconciliation covers them. Migration `0024_spend_caps.sql` |
| 932 | backfills the current month from the ledger. |
| 933 | |
| 934 | **Why it differs from the statement.** The section is the calendar month |
| 935 | so far, today included, counted as each charge settled: the model |
| 936 | providers' cost and the price book's cost of sandboxes and builds. The |
| 937 | statement is the range, reconciled against Cloudflare's bill, where |
| 938 | sandboxes inside Cloudflare's included usage cost $0. Both count |
| 939 | Cloudflare's subscriptions the same way: each day its billing cycle's share |
| 940 | of the month's price (`SpendCaps.fixed_month_micros` here, the month's days |
| 941 | so far). And `g1t_spend` is never wiped: spend on a workspace a testing reset |
| 942 | wiped later stays here (sudo names it, `SpendCaps.reset_micros`), while the |
| 943 | statement has it only where the reset kept it (`reset_costs`, given away as |
| 944 | testing resets). syntaqx's $7.41 of 2026-10-02 to 10-05, reset on 10-07 |
| 945 | before resets kept their cost, is that case. |
| 946 | |
| 947 | ### Caps |
| 948 | |
| 949 | | Cap | Variable (g1t-billing) | Default | At the cap | |
| 950 | | --- | --- | --- | --- | |
| 951 | | A comped account's monthly budget | `COMPED_MONTHLY_CEILING_MICROS`, or the account's own **Limit** in its terms | $150 a month | New work on the account (agents, checks, workflows, builds) is refused with "<name>'s monthly budget for g1t's own agents is used up … Staff can raise it in sudo". Runs already going finish; the per-run cap still applies to them. It lifts when staff raise the budget or the month turns (UTC). | |
| 952 | | The daily breaker | `PLATFORM_DAILY_SPEND_CAP_MICROS` | $75 a day (UTC) | New agent runs on g1t's hosted models that g1t would pay for are refused until 00:00 UTC. Not paused: agents on the workspace's own model provider, checks and builds, and workspaces paying with live payments on the plan (not given by staff) or an enterprise contract. In test mode that exemption covers no one. | |
| 953 | |
| 954 | `0` turns either off. Cloudflare's subscriptions are read from Cloudflare |
| 955 | each day (`cf_subscriptions`) and shown on the page only, accrued day by |
| 956 | day; `CLOUDFLARE_FIXED_MONTHLY_MICROS` ($30) stands in until a read works. |
| 957 | |
| 958 | The checks are cheap: `reserve` reads today's total (one indexed sum) and, |
| 959 | for a comped account, its month's comped rows. Refusals come back as |
| 960 | `paused`, which the compute gate honours for every plan, internal and |
| 961 | enterprise included (`packages/contracts/src/compute.ts`). The runner tells |
| 962 | billing whether an agent run is on hosted models (`hostedModel` on |
| 963 | `reserve`); a caller that does not say is treated as hosted. |
| 964 | |
| 965 | ### Alerts |
| 966 | |
| 967 | All to `COSTS_ALERT_EMAIL` (`hey@flagon.io`), through the `EMAIL` binding: |
| 968 | |
| 969 | - **Comped budget**: at 50, 75, 90 and 100%, once each per account and month |
| 970 | (`budget_alerts`), checked every 15 minutes. A jump past several levels |
| 971 | sends only the highest. |
| 972 | - **Breaker**: at once, from the charge that trips it; if that email fails, |
| 973 | the 15-minute cron sends it (`spend_breaker.told_at`). |
| 974 | |
| 975 | While the breaker is open or a comped budget is used up, every sudo page |
| 976 | shows a red **Spend cap** bar. |
| 977 | |
| 978 | ### Raising and lifting |
| 979 | |
| 980 | - **Raise a comped budget**: sudo → the workspace → Billing → **Terms**, set |
| 981 | **Limit $** to the new monthly budget (blank goes back to the default), |
| 982 | with a note. It applies to the next start; nothing to deploy. The change |
| 983 | is in the account's audit log. |
| 984 | - **Lift the breaker for today**: sudo → Costs & margin → **g1t's own |
| 985 | spend** → **Lift for today**, with why (`admin_lift_breaker`; audit action |
| 986 | `breaker_lifted`). It resets by itself at 00:00 UTC. |
| 987 | - **Change a default**: edit the variable in `services/billing/wrangler.jsonc` |
| 988 | and deploy g1t-billing. |
| 989 | |
| 990 | ## Resetting a test workspace |
| 991 | |
| 992 | sudo → the workspace → **Reset billing (testing)** (`admin_reset_billing`) |
| 993 | returns a workspace used for testing to how a new customer starts. It |
| 994 | deletes the workspace's rows from every billing table: ledger and balance, |
| 995 | plan and plan payments, limits and limit requests, trial grant, invoices, |
| 996 | holds, card checks, alerts sent, price notices, month-end snapshots and |
| 997 | closes, storage meters, token usage, spikes, sales records and |
| 998 | notes, `workspace_costs`, its workspace margin alert and its own billing |
| 999 | account. It keeps `own_counts` (what Cloudflare's bill is compared with) |
| 1000 | and the audit log, which records the reset with the note, the number of |
| 1001 | rows and what g1t had paid for. The workspace, its members and its |
| 1002 | repositories are identity's and repos' and stay. |
| 1003 | |
| 1004 | **What g1t paid for is kept.** The wiped usage still happened: AI Gateway |
| 1005 | still prices its model calls and Cloudflare still bills its sandboxes. So, |
| 1006 | in the same batch as the deletes, the reset writes `reset_costs`: a row per |
| 1007 | day and bucket the workspace had cost on (the ledger's cost, month-end |
| 1008 | meters' cost, and the value the reconciliation gave it), plus one row for |
| 1009 | the reset itself (bucket `''`, nothing in it) so every reset is on record. |
| 1010 | `reset_at` is the same instant as the reset's `admin_actions` entry. The |
| 1011 | costs run reads the rows back as the workspace's usage on their days, all |
| 1012 | of it given away as **testing resets**: `models` drift compares AI |
| 1013 | Gateway with the ledger's model cost plus what resets kept, the statement |
| 1014 | lists it under **Given away**, and the workspace stays in **Who g1t paid** |
| 1015 | with its cost given. The rows are never wiped by a later reset, and a |
| 1016 | rename moves them. Re-running the analysis reads the same rows and gives |
| 1017 | the same answer. |
| 1018 | |
| 1019 | Resets before migration 0046 kept nothing; their wiped rows are gone and |
| 1020 | nothing is made up for them. The costs run finds them in the audit log |
| 1021 | (`admin_actions`, action `reset`) with no `reset_costs` at the same |
| 1022 | instant, and the `models` drift detail says AI Gateway's figure includes |
| 1023 | usage wiped by a testing reset of that workspace on that day, rather than |
| 1024 | calling it a leak. syntaqx was reset on 2026-10-07 after about $8.60 of |
| 1025 | model usage from 2026-10-02 to 2026-10-07; that usage is in the 7-day |
| 1026 | window until the run of 2026-10-13 and leaves it on 2026-10-14. |
| 1027 | |
| 1028 | Billing refuses it while `STRIPE_SECRET_KEY` is a live key, for comped |
| 1029 | workspaces, and for a workspace an enterprise pays for. It then runs the |
| 1030 | costs analysis again (as **Run the analysis now** does), so the margin |
| 1031 | figures drop the workspace's past usage at once; if that run does not |
| 1032 | finish, the page says so and the button does it. |
| 1033 | |
| 1034 | ## Stripe |
| 1035 | |
| 1036 | Billing keeps what it needs from Stripe so reads never wait on it, and |
| 1037 | hears of changes three ways (`webhooks.rs`, `stripe_sync.rs`). |
| 1038 | |
| 1039 | **API version.** Every request sends `Stripe-Version: 2025-02-24.acacia` |
| 1040 | (`stripe::STRIPE_VERSION`), the version billing's field reads are written |
| 1041 | for; without it Stripe answers at the account's default. Webhook events |
| 1042 | come at the destination's own version: billing reads an invoice's |
| 1043 | subscription from `subscription` or `parent.subscription_details.subscription`. |
| 1044 | Raising the version is a code change: read Stripe's upgrade notes for every |
| 1045 | field billing reads. |
| 1046 | |
| 1047 | **Failures.** No Stripe failure reaches a page as a 500: each payment page |
| 1048 | (`page_opened`), the portal, confirmations and plan changes turn it into |
| 1049 | `stripe::friendly` (Stripe's own message, never the request or a key), and |
| 1050 | log the full error with the workspace. Every payment page is recorded |
| 1051 | through one insert (`CHECKOUT_INSERT`), checked against the migrations by |
| 1052 | `every_checkout_insert_fills_the_table`, and has an idempotency key |
| 1053 | (`page/<purpose>/<workspace>/…/<10-minute bucket>`). |
| 1054 | |
| 1055 | **The webhook.** A destination made in Stripe's dashboard (Developers → |
| 1056 | Webhooks → Add destination) with the endpoint URL |
| 1057 | `https://api.g1t.sh/stripe/webhook`, in the mode of billing's key (at |
| 1058 | launch, make one in live mode and put its secret). Its signing secret |
| 1059 | (`whsec_…`: the destination, Signing secret, Reveal) is the billing |
| 1060 | Worker's secret: |
| 1061 | |
| 1062 | ```sh |
| 1063 | cd services/billing && npx wrangler secret put STRIPE_WEBHOOK_SECRET |
| 1064 | ``` |
| 1065 | |
| 1066 | Without it every event is refused with 400. After rolling the secret in |
| 1067 | Stripe, put the new one; during the roll Stripe signs with both, so there |
| 1068 | is no gap. The event list need not be exact: billing adds any event it |
| 1069 | handles that the destination does not send (daily, or **Fix destination** |
| 1070 | in sudo → Stripe), and enables it again if Stripe disabled it. It never |
| 1071 | changes the secret. sudo → Stripe shows whether the secret is set, the |
| 1072 | destination and its status, missing events, and the latest events. |
| 1073 | Events are claimed once each in `stripe_events`; a handler that fails |
| 1074 | forgets its claim, and Stripe retries. |
| 1075 | |
| 1076 | **What is kept, and how it stays current** |
| 1077 | |
| 1078 | | Kept | Where | Refreshed by | |
| 1079 | | --- | --- | --- | |
| 1080 | | Saved card (brand, last 4, expiry) | `accounts.card_*`, `card_synced_at` | `customer.updated`, `payment_method.*`, `setup_intent.succeeded`; forgotten when g1t sets a default card, so the next read asks once; the daily pass for cards older than 7 days | |
| 1081 | | Plans | `subscriptions` | `customer.subscription.*`, `invoice.*`; a read asks Stripe at most hourly once a period is over; the daily pass for rows older than a day | |
| 1082 | | Payments, refunds, disputes | ledger, `checkouts`, invoices | their events | |
| 1083 | |
| 1084 | **Every cron run (every 15 minutes)** replays missed events: Stripe's event |
| 1085 | list from an hour before `stripe_sync.through`, oldest first, through the |
| 1086 | same once-only claim. `through` moves to 5 minutes before now when all were |
| 1087 | handled, back to the first failure otherwise, and stays when more than |
| 1088 | 1,000 events were listed. Claims stuck at `handling` for 10 minutes are |
| 1089 | dropped so the replay retries them. The first run reads 3 days back. |
| 1090 | |
| 1091 | **Daily** (`keeper::DAILY`): the destination at billing's address is |
| 1092 | enabled again if Stripe disabled it and given any missing event, audited as |
| 1093 | `stripe`/`webhook`; then up to 25 stale cards and 25 stale plans are read |
| 1094 | again. |
| 1095 | |
| 1096 | **What still calls Stripe on a request**: starting a payment page, a plan |
| 1097 | or a card check; opening the billing portal; settling a page the person |
| 1098 | came back from; renaming a workspace (the customer's name). Nothing a page |
| 1099 | view reads. |
| 1100 | |
| 1101 | ## Tax and the card fee |
| 1102 | |
| 1103 | Owner decision 2026-10-08. Code: `services/billing/src/tax.rs` (what is |
| 1104 | kept, the address hold), `stripe.rs` (every request's tax fields), |
| 1105 | `invoices.rs`, `webhooks.rs`, `ai.rs`; migration |
| 1106 | `0043_tax_and_card_fees.sql`. |
| 1107 | |
| 1108 | ### What Stripe is asked |
| 1109 | |
| 1110 | Every price excludes tax (`tax_behavior=exclusive`) and carries tax code |
| 1111 | `txcd_10103001` (software as a service, business use; the card fee too, |
| 1112 | since a fee for paying for a sale follows the sale). Fields are valid for |
| 1113 | `2025-02-24.acacia`. |
| 1114 | |
| 1115 | | Request | Tax | Card fee | |
| 1116 | | --- | --- | --- | |
| 1117 | | Checkout, plan or Security (`subscription_fields`) | `automatic_tax[enabled]`, `billing_address_collection=required`, `tax_id_collection[enabled]`, with a customer `customer_update[address]=auto` and `[name]=auto`; the subscription keeps automatic tax for every renewal | A second recurring line, *Card processing fee* | |
| 1118 | | Subscription on a saved card (`saved_subscription_fields`) | `automatic_tax[enabled]`; a customer Stripe Tax cannot place fails, and the person is sent to Checkout, which asks for the address | `items[1]`, the `card_fee` product | |
| 1119 | | Checkout, prepay (`prepay_fields`) | As above | By card only; none by bank transfer | |
| 1120 | | Checkout, AI credit (`credit_fields`) | As above | Its own line | |
| 1121 | | Checkout, card check (`card_check_fields`) | Setup mode: nothing charged, nothing taxed. `billing_address_collection=required`, and the card's address is copied onto a customer with none (`fill_address`) | — | |
| 1122 | | Auto-reload (`charge_saved`) | `POST /tax/calculations` first (credit and fee as lines), the PaymentIntent for the total, then `POST /tax/transactions/create_from_calculation` with the PaymentIntent as reference; a refund reverses its share (`create_reversal`, `mode=partial`) | In the calculation and the amount | |
| 1123 | | Workspace invoice, month close and threshold (`invoice_workspace`) | `automatic_tax[enabled]` on the draft; each item `tax_behavior`, `tax_code` | An item *Card processing fee*, when the default payment method is a card | |
| 1124 | | Enterprise invoice (`invoice_enterprise`) | The same | Never | |
| 1125 | | Products (`Stripe::product`) | Made with `tax_code`; one found without it is given it | The `card_fee` product, `metadata[g1t]=card_fee` | |
| 1126 | |
| 1127 | ### What is kept |
| 1128 | |
| 1129 | A payment credits the balance with what it paid for, never its tax or fee: |
| 1130 | prepay credits the page's `amount_subtotal` less the fee line |
| 1131 | (`credit_prepayment`), a workspace invoice `amount_paid − tax − fee` |
| 1132 | (`credit_invoice`), AI credit its credit amount, and `plan_payments` the |
| 1133 | plan's invoice less its tax and *Card processing fee* lines |
| 1134 | (`stripe::invoice_split`). Each payment's tax and fee are rows in |
| 1135 | `tax_and_fees` (`<reference>/tax`, `<reference>/card_fee`; the enterprise's |
| 1136 | account id in `workspace` for its invoices), with the PaymentIntent, so a |
| 1137 | refund (`charge.refunded`) gives back the balance, tax and fee in |
| 1138 | proportion (`tax::refund_split`, negative rows under `refund/<charge>/…`). |
| 1139 | `workspace_invoices.fee_micros` and `tax_micros` sit beside each usage |
| 1140 | invoice. |
| 1141 | |
| 1142 | - **Statement.** *Tax* and *Card processing fees* are their own lines per |
| 1143 | day (`StatementLine.passed_micros`), never in `charged_micros`; totals |
| 1144 | `tax_micros`, `card_fee_micros`. The CSV has a row a day for each. |
| 1145 | - **Margin.** Cash never holds them, so margin is untouched. sudo → Costs |
| 1146 | shows **Tax collected** and **Card fees passed on** for the range |
| 1147 | (`OverallMargin.tax_collected_micros`, `card_fees_micros`). Tax is owed to |
| 1148 | the authorities: file it from Stripe Tax's reports, never from g1t's. |
| 1149 | |
| 1150 | ### No address |
| 1151 | |
| 1152 | Stripe Tax needs a country (in the US a ZIP code, in Canada a postal code |
| 1153 | or province: `stripe::address_places_customer`). Before a workspace |
| 1154 | invoice is drafted, g1t checks the customer; without an address, or when |
| 1155 | Stripe leaves the draft at `requires_location_inputs` or refuses with |
| 1156 | `customer_tax_location_invalid`, nothing is charged: |
| 1157 | `accounts.tax_address_needed_at` is set, the owners are emailed once |
| 1158 | (`notify_owners`), and Billing shows **Add a billing address**. Saving |
| 1159 | Invoice details with an address Stripe Tax can use clears it, as does a |
| 1160 | charge that goes through. Work is not stopped for it; the limits still |
| 1161 | apply. Auto-reload without an address fails like a declined card (turned |
| 1162 | off, owners told). An enterprise's invoice is not sent without an address: |
| 1163 | sudo → the enterprise → Invoices → **Billing address** (`admin_enterprise_address`, |
| 1164 | with its tax ID; audited `billing_address`). |
| 1165 | |
| 1166 | ### The card fee |
| 1167 | |
| 1168 | `card_fee_cents` grosses Stripe's fee up so the amount paid for is left |
| 1169 | after it: `(amount + 30¢) / (1 − 2.9%)`, rounded up; $0.91 on $20, $1.06 |
| 1170 | on $25. It is worked out on the amount before tax, so Stripe's fee on the |
| 1171 | tax itself (a few cents) is g1t's. It is shown before paying: the plan card |
| 1172 | and pricing page (`Plan.card_fee_cents`), AI credit (*Card processing fee |
| 1173 | $1.06, plus tax where it applies*), Prepay. Never on a bank transfer or an |
| 1174 | enterprise's (`send_invoice`) invoice. Meters stay at cost + 20% and models |
| 1175 | at the provider's price plus the agent rate (price versions in migration |
| 1176 | 0040); the fee is passed through, not margin. |
| 1177 | |
| 1178 | ### Tax-exempt customers and tax IDs |
| 1179 | |
| 1180 | g1t never sets `tax_exempt`. For a customer who sends an exemption |
| 1181 | certificate, set it in Stripe's dashboard (Customers → the customer → Tax |
| 1182 | status: Exempt, or Reverse charge); Billing then says so. Tax IDs come |
| 1183 | from Checkout (`tax_id_collection`) or Invoice details (`set_billing_details`, |
| 1184 | validated against Stripe's types in `details::TAX_ID_TYPES`); Stripe checks |
| 1185 | EU VAT numbers and Stripe Tax applies a reverse charge where it should. |
| 1186 | Billing shows Stripe's `verification.status`. |
| 1187 | |
| 1188 | ### In Stripe's dashboard (not done by g1t) |
| 1189 | |
| 1190 | 1. **Settings → Tax → Get started**: turn on Stripe Tax in live and test |
| 1191 | mode. |
| 1192 | 2. **Origin address**: Flagon, Inc.'s head office address. |
| 1193 | 3. **Default tax code**: Software as a service, business use |
| 1194 | (`txcd_10103001`); **default tax behavior**: exclusive. |
| 1195 | 4. **Registrations**: add each jurisdiction where Flagon is registered to |
| 1196 | collect (its home state at least; then states as thresholds are |
| 1197 | crossed, which Stripe Tax's monitoring flags; the EU's OSS and the UK |
| 1198 | if selling there). Stripe collects only where a registration exists. |
| 1199 | 5. **Customer portal**: tax ID and address updates are already allowed |
| 1200 | (`portal_configuration`). |
| 1201 | 6. Refund an invoice through a **credit note**, so its tax is reversed in |
| 1202 | Stripe Tax. |
| 1203 | |
| 1204 | ## Free workspaces |
| 1205 | |
| 1206 | Owner decision 2026-10-08: one free workspace per person, and a free |
| 1207 | workspace adds no one. Billing answers one question, `free_workspaces` |
| 1208 | (`credits.rs`): which of the given workspaces are on no paid plan |
| 1209 | (`plan_kind_for` is `Free`). The plan, an enterprise's terms and a 100% |
| 1210 | discount (flagon-io) count as paid; with payments off nothing is free. |
| 1211 | Identity asks it (`services/identity/src/paid.rs`) and refuses with |
| 1212 | `payment_required`: |
| 1213 | |
| 1214 | | Where | Refused when | |
| 1215 | | --- | --- | |
| 1216 | | `create_workspace` | The person owns any free workspace. Several from before are kept (grandfathered); none can be added until each is paid for or deleted. | |
| 1217 | | `add_member`, `invite_member` | The workspace is free. | |
| 1218 | | `add_collaborator` | Someone outside a free workspace (a username who is not a member, or an address). Members' roles are fine. | |
| 1219 | | `accept_invite`, `respond_repo_invitation` | The invite's workspace (or repository's) is free now: it waits. A sign-up with such an invite makes the account without joining. | |
| 1220 | |
| 1221 | `@g1t` is never counted as someone added. If billing cannot be asked, the |
| 1222 | change is refused for now ("try again"), never let through. The site says |
| 1223 | so first (New workspace, People, a repository's Access, from the same RPC); |
| 1224 | the API and MCP pass identity's refusal on as `402`. |
| 1225 | |
| 1226 | ## The Security and quality activation |
| 1227 | |
| 1228 | A second monthly subscription a workspace can hold beside the plan |
| 1229 | (`Feature::Security`, `feature = 'security'` in `subscriptions`). It turns |
| 1230 | on the security suite's paid features for the workspace's private |
| 1231 | repositories: custom secret patterns, validity checks, delegated bypass, |
| 1232 | code scanning, dependency review and the security overview. Public |
| 1233 | repositories have them free; secret scanning, push protection, |
| 1234 | vulnerability alerts and security updates are free everywhere. |
| 1235 | |
| 1236 | - **Price.** The price book's `security_activation` meter (unit |
| 1237 | `workspace-month`, `source` `list`, markup 0): 10,000,000 micros, $10, |
| 1238 | from migration `0037_security_activation.sql` with its first |
| 1239 | `price_versions` row and a public `price_changes` record. `plan()` and the |
| 1240 | `prices` RPC read it (`features::security_plan_at`); if the price book |
| 1241 | cannot be read, $10. Nothing in the web app hard-codes it. A change is a |
| 1242 | new price version, like any other: noticed on the pricing page and |
| 1243 | applied from its `effective_at` to new subscriptions. Subscriptions |
| 1244 | already running keep the amount Stripe has until they are changed in |
| 1245 | Stripe. |
| 1246 | - **Stripe.** Its own subscription and its own product, tagged |
| 1247 | `metadata[g1t]=security` (the plan's is `plan`). Started from the Billing |
| 1248 | page with `subscribe` (`feature: security`) on the checked card, or |
| 1249 | through Checkout; ended with `cancel_subscription` (`feature: security`) |
| 1250 | at the period's end. Its invoices count in `plan_payments` like the |
| 1251 | plan's, as paid revenue. |
| 1252 | - **Who has it.** `has_feature(workspace, security)`: on with an active |
| 1253 | subscription, with comped terms or as an enterprise's workspace, or when |
| 1254 | Stripe is not configured. The plan's allowance (`allowances.plan`) does |
| 1255 | not include it. Refusals are `PaymentRequired` with the price from the |
| 1256 | price book and the Billing page's address. |
| 1257 | - **Where it is checked.** The security service, on each paid call for a |
| 1258 | private repository (`suite::entitled`) and before using custom patterns |
| 1259 | in a push (`patterns_for`). When billing cannot be reached it is taken |
| 1260 | as off: a paid feature waits rather than running unpaid. |
| 1261 | - **Fixes.** "Fix with g1t" runs g1t's agent, charged as agent usage, never |
| 1262 | to the activation. |
| 1263 | - **Sales figures.** MRR in sudo counts `feature = 'plan'` only; the |
| 1264 | activation's subscriptions are not in it yet. |