How to bill a fixed-price coding task with AI assistance while keeping human approval

A fixed-price job has two numbers, and both are billing figures. The first is the flat price you agreed with the client. The second is what the approved policy computes from the task: measured active time at the policy rate, plus reported provider usage multiplied by the usage multiplier.

Billr produces the second number. It is not a statement of your actual costs, your margin, or your profit: the rate and the multiplier are whatever a person approved, and the usage rows are reported provider charges. What the record gives you is an auditable comparison, so the next fixed-price quote can be based on something other than memory.

The permission boundary is what makes this usable with an agent in the loop. An agent can run the work and report usage. It cannot set the rate, approve the pricing for this task, or release it for invoicing. Ordinary invoices are a different matter: with a Read and draft key an agent can create and edit drafts, including the one this approval produces, and with the Billing profile it can also send invoices and record payments.

Task billing starts in the app. An owner or admin creates a policy for a client with a currency, an hourly rate, a usage multiplier and a budget per task. Existing tasks keep the policy they were created under, so changing a rate later does not rewrite history; it creates a new rate for new work.

The agent then reads the policies and picks the right one. Pricing it cannot see is pricing it cannot bill against, which is the whole point of the boundary. The scope what an agent may do guide explains which key profile covers which tools.

list_billing_policies  { "business_id": "b1f2c3d4-5e67-4a89-9b01-2c3d4e5f6a7b" }

create_task opens the task in a paused state with a title and a policy id. Nothing is charged until start_task. From then on the clock is server-measured: heartbeats record elapsed time, and only the first 120 seconds after a heartbeat count. A session that goes quiet is not quietly billing.

That cap shapes the operating rule. Send heartbeat_task every 30 to 60 seconds while the agent is actively working, and pause_task whenever it is waiting on you, on a review, or on a slow external resource. If you are waiting for a person, the task should be paused. The run a billable task guide lists the whole lifecycle in order.

create_task  {
  "request_id": "f3d7a1b9-5c28-4e64-8a09-2b6d4f1c7e35",
  "policy_id": "0d9c2b64-7f13-4e88-9a25-1c6b3e8d4f70",
  "title": "Accessibility remediation pass"
}
start_task  {
  "request_id": "2e8b5c41-6a07-4d38-8f52-3e7a1c9b0d64",
  "task_id": "c8a3f0d5-4b17-4e92-9c60-2d5b8f1a7e39"
}
heartbeat_task  {
  "request_id": "9b2e5c41-6a07-4d38-8f52-3e7a1c9b0d64",
  "task_id": "c8a3f0d5-4b17-4e92-9c60-2d5b8f1a7e39"
}

record_task_usage records one provider charge: the provider, a provider request reference, the cost in the policy currency and a source string explaining where the figure came from. Model name, input tokens and output tokens are optional but worth including, because they are what let you reconcile the row against your provider dashboard later.

Usage rows are unique per business, provider and provider reference. Recording the same provider charge twice is rejected rather than quietly doubling the amount, and a retry with the same request_id returns the original.

record_task_usage  {
  "request_id": "3c7d1a86-5e29-4b04-9f71-6a2d8c4b1e95",
  "task_id": "c8a3f0d5-4b17-4e92-9c60-2d5b8f1a7e39",
  "provider": "anthropic",
  "model": "claude-sonnet-4",
  "provider_request_id": "req_01HZY8QK4M",
  "cost": 216,
  "currency": "USD",
  "input_tokens": 184500,
  "output_tokens": 26400,
  "source": "provider usage export, weekly download"
}

complete_task stops the clock and freezes the work for review. Then get_task_billing_preview reports the two components and the total: active time at the policy rate, reported usage multiplied by the approved multiplier, both rounded per component, plus requires_human_review and a review_url.

The worked example below is a job agreed at a flat 1,500.00 where the computed amount came in lower. That is the useful case: the record shows how the approved policy priced the work, while the agreement still decides what the client pays.

{
  "time_amount": 1230,
  "usage_amount": 237.6,
  "total": 1467.6,
  "currency": "USD",
  "requires_human_review": true,
  "review_url": "/tasks"
}

1. A person opens the review url, reads the active time and each usage row, and approves the pricing.
2. Approval writes a draft invoice from the policy: one line for active time and one for multiplied usage, with the task linked to that invoice. Deleting the draft releases the task back to completed so it can be approved again rather than leaving billing in a half state.
3. Check the draft against the agreement. If the job was agreed at a flat price, replace the lines with that single agreed amount using update_draft_invoice, which only works while the invoice is still a draft.
4. Do not also draft a second invoice for the same work. One task maps to one invoice, so a duplicate is the thing to avoid. If you have already created one by mistake, delete the unsent draft in the app rather than sending either.
5. Send when the draft is right: send_invoice, or the Send action in the app.

update_draft_invoice  {
  "invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11",
  "line_items": [
    {
      "description": "Accessibility remediation pass, agreed flat price",
      "quantity": 1,
      "rate": 1500
    }
  ],
  "notes": "Agreed flat price. Task record shows $1,467.60 computed under the approved policy ($1,230.00 time and $237.60 usage)."
}

• Under the agreed price: invoice the agreed price, and keep the preview as the record of what the approved policy computed. Nothing about the client conversation changes.
• Over the agreed price: you now have dated evidence of what took the time, including the usage rows. That is material for a scope conversation rather than a surprise invoice.
• Work that stalls: pause instead of letting a task idle. Time only counts in the measured windows after a heartbeat.
• A repeated provider charge: the uniqueness on business, provider and request reference rejects the duplicate. If the provider genuinely charged twice, record it with the second reference.

Two operational limits are worth planning around. The pricing policy is per client and per task history, so a rate change means a new policy for new work rather than an edit that rewrites old amounts. And task work is tracked separately from logged time: a task measures its own active seconds instead of the hours you would log with log_time, so bill one or the other for the same work, never both. The bill a month of logged work guide covers the logged-time path.