DocsReference / How billing works

How billing works

A plumber pays for a booked job, not for a visit. That is the whole model: one charge when a real outcome happens, nothing when it does not. This page defines the unit precisely — and separates the part that is built and tested today from the part that is still a design.

The unit: a verified completed action

Three words, each doing work.

Verified
The business owner has seen this action, approved it, and set the terms: the hours it may run, how many an agent may create in a day, which fields an agent may fill, and where they get notified. Until that has happened the action exists only in test mode, and there is no path around it.
Completed
A real outcome happened at the far end — a booked job, a submitted quote, an appointment made. Not an attempt. Not a page view. Not an agent reading the catalogue and deciding against it.
Action
One entry in the site’s Action Graph, with its inputs, its declared rules and its stated consequences. Not a session, not a conversation, not a lead.

Duplicates do not count. Attempts do not count. A failed action does not count, and neither does an action an agent started and abandoned.

The half that is built: what "verified" means in code

The billable unit begins with a gate, and the gate exists. It lives in the schema package rather than in a service, deliberately, so the rule and the data shape it checks ship and version together — a service cannot end up gating on a stale idea of what verified meant.

It refuses everything that is not a positive, fully-evidenced yes. It never trusts a status string; it re-derives permission from the confirmation record every single time. It takes an untyped value, so a cast at a call site cannot satisfy it. And every property read on the permission path goes through an own-property check, because plain property access walks the prototype chain and an adversarial review once used that to grant live execution to an empty object.

For an action to pass, all of this must be true at once: there is a confirmation; it names who confirmed and when; it points at a retrievable audit record; it authorises at least one field; it caps the volume per day as a real positive integer; it names at least one notification channel; and the disclosure the owner acknowledged still matches what the action does today, field for field, including the summary sentence compared byte for byte.

The half that is designed: metering, dedupe and replay

Everything in this section is the intended model. None of it is running, and no figure below is measured, because there is nothing to measure yet.

What the metering layer is designed to do
ConcernThe intended answerState
CountingOne record per completed action, attributed to the agent identity where the agent offers one, and to the business it ran against.In development
DuplicatesThe same outcome created twice — a retry, a double submit, two agents sent by the same person — is one billable action, not two.In development
Fraud and velocityRate limits per agent identity, velocity checks, and honeypots. Not a CAPTCHA: a CAPTCHA stops a customer’s agent exactly as well as it stops a bot.In development
ReplayEvery executed action logged so it can be replayed. An argument about whether a booking happened is settled by the record rather than by opinion.In development
NotificationThe owner is told, in real time, every time an action fires — on a channel they nominated when they approved it. An authorisation with no notification channel is refused by the gate today.Gate check built · delivery in development
Audit exportThe business can export the log of what ran against them.In development

Source: docs/03-build-architecture.md · components 4, 7, 8 and 9

Why attribution is settled by the record

Per-action pricing has one obvious failure mode and it is worth naming rather than discovering: a dispute about whether an action really happened, or whether it was already going to happen anyway. That risk is on the record in the go-to-market document, and the answer designed against it has three parts.

First, the action was approved in advance, with the approval stored as data rather than as a tick in a settings screen. What the owner agreed to is retrievable, including the exact sentence they read.

Second, the agent is identified where it offers identification. The Web Bot Auth headers are the current mechanism — and note carefully what today’s code does with them: the tracker detects those headers and does not verify the signature. The claim available right now is "this request presented a signed agent identity", not "this is a verified agent". Verifying the signature is work that belongs with an executing layer, where it would actually matter, and it is not done.

Third, every execution is logged and replayable. Not summarised — replayable. The point is that a disagreement between a business and us has an answer that neither of us writes on the day.

What is never billable

  • The scan. It is free, and the fix list that comes with it is the whole list — nothing is held back for a paid tier.
  • The tracker. Free forever. There is no account and nothing to buy at the end of it.
  • An attempt. An agent that tried and could not finish costs nothing, and it is arguably the most useful thing in the report.
  • A duplicate of an outcome already counted.
  • Anything on an action the owner has not verified — because that cannot run at all.

The price

The model is a charge per verified completed action, set per vertical, and it is deliberately not published here. Whether ranges go public before the first round of validation calls is a decision for the founder rather than a detail of a documentation page, and the pricing page is built so that answer is a single switch.

What can be said without a figure: the charge is meant to sit under what a business already pays for a lead in its own trade, and it only ever applies to an outcome that happened.

Written from

  • What "verified" means, in codepackages/shared/src/trust.ts
  • What the owner authorisespackages/shared/src/types.ts
  • The nine-component pipelinedocs/03-build-architecture.md
  • The pricing model and the risks against itdocs/04-gtm-pricing.md
  • Current state of every componentdocs/STATUS.md