Billing and quotas

Capability codes

A capability code such as routing.optimize serves four roles simultaneously: the billing SKU, the authorization scope for REST and GraphQL, the MCP tool scope, and the documentation anchor. The same string is therefore used to enable a capability, grant it to a key, expose its tool to an agent, and identify it on an invoice.

Codes are permanent. They are not renamed, reused, or redefined. Adding a parameter to an existing capability does not require a new code; changing what is billed does, and the previous code is deprecated rather than altered, because invoices, key scopes, agent tool lists and monitoring all key on that string.

Charges in the response

Every billable response reports its own cost:

"billing": {
  "unit": "node",
  "quantity": 412,
  "counted": true,
  "breakdown": { "nodes": 412, "jobs": 400, "vehicles": 6, "vehicle_nodes": 12 }
}

breakdown allows a charge to be reconciled against the request that produced it.

Definition of a node

Routing is billed per node. A node is any point the solver must visit or depart from, including each vehicle's start and end location. Nodes are not equivalent to delivery stops: a problem with ten vehicles and two jobs comprises two stops and twenty-two nodes. The distance matrix is constructed over nodes, which is why they determine the cost of the solve.

• A job contributes 1 node.
• A shipment contributes 2 (a pickup and a delivery).
• A vehicle contributes 2 (start and end), reduced to 1 where both are the same location or where return_to_start is set, and 0 where neither is specified.

Quotas

Each capability may carry an included volume and a monthly or daily limit. Behaviour beyond the included volume is determined by the account's overage_policy:

Policy	Beyond the included volume
block	Calls are refused with 402 QUOTA_EXHAUSTED.
bill	Calls continue and the overage is invoiced.
require_confirm	Calls continue, but an agent connected over MCP must confirm before incurring the charge.

require_confirm is intended for agent-driven usage. Where it applies, the tool is presented as requiring confirm=true, so that expenditure beyond the purchased plan is an explicit decision rather than an incidental one.