How to bill clients for AI usage

1. Agree the basis before the work. Pass-through, cost plus markup, an allowance or a fixed price, in one currency, for a stated period. A charge the client first hears about on the invoice is a dispute waiting to happen.
2. Track costs with evidence. Every usage charge should point to a provider request reference and to the record it came from, so you or the client can check it later.
3. Keep provider cost and client price apart. What the provider charged you is an input. What the client owes is whatever your agreement says to do with that input.
4. Review before you invoice. Read the usage rows, compare them with the provider's own records, and check the draft totals before anything is sent.

This guide is about deciding and explaining the charge. The API steps for recording a task are in Run a billable task, and the exact formulas and limits are in Task billing.

These are commercial choices you make with the client. Billr supports some of them directly and leaves the rest to your agreement; the last column says which.

A task pricing policy has four settings: currency, hourly rate, usage multiplier and a budget per task. That covers pass-through and cost-plus directly. To track your own cost on fixed-price or allowance work without charging for it, set both the hourly rate and the usage multiplier to 0. A multiplier of 0 on its own is not enough: any recorded active time is still charged at the hourly rate. A task whose total is zero cannot be turned into an invoice and stays as a completed record. Retainers and fixed prices belong in an engagement, which holds an agreed total and its payment schedule. Counting usage against an allowance and deciding on overage is still your job.

Markup is the uplift as a share of your cost. Margin is the same uplift as a share of the price the client pays. They are different numbers for the same charge, and mixing them up underprices the work.

price  = cost × (1 + markup)
margin = (price − cost) ÷ price
multiplier for a target margin = 1 ÷ (1 − margin)

If you mean “I keep 20% of what the client pays”, the multiplier is 1.25, not 1.2. Write the agreement in the form you will calculate with, and use the word you mean.

Four different numbers get called “AI cost”. Only one of them is something a provider actually charged you.

Reported provider cost

The amount in the provider's own usage or billing records for a specific request or batch.

In Billr: What record_task_usage is for. Billr stores the amount you or your agent supply with its reference and source; it does not fetch it or check it against the provider.

Token or rate estimate

Token counts multiplied by a published price, computed by you or your tooling.

In Billr: An estimate, not a charge. The tool description asks agents not to submit estimates. Wait for the provider record, or agree in writing that you bill estimates.

Subscription allocation

A share of a flat seat or plan fee, split across clients by a rule you choose.

In Billr: A flat fee is not evidence of what any single request cost, so it is not something to report as task usage. If you charge for it, bill it as an agreed line or expense and say how it was split.

Client price

What the client owes under your agreement: cost, cost plus markup, a share of a retainer, or nothing extra.

In Billr: The policy multiplier turns reported cost into this number. Billr adds no platform fee to it.

Agent session time is another number that is easy to misuse. A task's active seconds measure how long an agent reported being busy, from server-side heartbeats. They are not your working hours and not a measure of effort. If you bill your own time, log it as time; if you bill agent time, say so in the agreement and give it its own rate.

A short written section in the proposal or statement of work is enough. It should answer:

• Which basis applies, and the exact markup or multiplier.
• Which services and keys are in scope, ideally a key or project used only for this client, so the provider's records separate cleanly.
• The invoice currency, and what happens if the provider bills in a different one.
• The billing period, and whether usage is billed monthly or per deliverable.
• Whether calls that failed, or were rerun because of your own mistake, are billed.
• A cap, and what happens when it is reached: stop, ask, or continue.
• What evidence the client can ask for, such as the provider export rows.
• Whether your hourly rate already includes tool subscriptions.

Contract terms, tax treatment of rebilled costs and invoice requirements vary by country and by contract. Check them with an adviser where you work; this guide does not cover them.

Fictional. Harbor & Lane, the provider example-provider, the request references and every amount are invented for this guide. They are not real prices from any vendor and not output from a real account.

The agreement, signed before work began: human work at $120.00 an hour; embedding API usage on a project key used only for this client, billed at reported cost plus 20.00%; USD; billed monthly for September 2026; each usage task capped at $150.00 including markup; agent session time not billed; reruns caused by our own mistakes not billed.

Human time

6.5 hours × $120.00 = $780.00. These are ordinary time entries. In this example they are not also charged as task time: they are not on the usage task, and its policy charges nothing for active time.

Reported provider cost

The second usage report timed out on the way to Billr. The agent retried it with the same request_id and identical input, and got the original result back instead of a second $19.67 row. A retry with a fresh request id but the same provider reference would have been refused, because each provider reference can be recorded once per business and provider.

The arithmetic

Human time       4.25 h + 2.25 h at $120.00/h = $780.00
Reported cost    $38.42 + $19.67 = $58.09
Usage charge     $58.09 × 1.2 = $69.708, rounded to $69.71
Markup earned    $69.71 − $58.09 = $11.62 (margin 16.67% of the usage line)
Agent time       0 seconds at $0.00/h = $0.00
Client total     $780.00 + $69.71 = $849.71

The multiplier is applied once, to the task's summed cost, and rounded to cents once. Multiplying and rounding each row separately can land a cent away from what Billr computes. The example excludes tax and discounts: neither draft carries a tax rate, discount or shipping amount.

What Billr creates: two invoice drafts

Billr creates the task's invoice from the task itself, and the time invoice from the time entries. They are two drafts, and both stay internal until you review and send them. Do not copy the usage amount onto the time invoice by hand: the task would stay approvable and the same usage could be invoiced again.

Together: $780.00 + $69.71 = $849.71 for September. The task draft keeps the server's line wording, including a $0.00 active-time line, and its notes default to “Approved task: Catalog re-embedding run”. Edit the notes and wording on the draft so the client can follow it; the amounts should still match the approved preview.

1. 01A person approves the pricing

   An owner or admin opens Task billing and approves a policy for the client: currency USD, hourly rate 0, usage multiplier 1.2, budget $150.00 per task. Agents can read policies with list_billing_policies but cannot create or change them. A new rate means a new policy; existing tasks keep the one they started with.

2. 02The agent records usage on a task

   The agent creates a task under that policy and reports each provider charge as it gets the record. With an hourly rate of 0, there is no need to start the clock.

   >_ Tool call, fictional valuesCopy

   record_task_usage  {
     "request_id": "0f7c4b2e-9d61-4a83-b5e2-6c1a8f3d9e74",
     "task_id": "e3b9d7a2-6f41-4c08-9d25-1a7c5e8b0f63",
     "provider": "example-provider",
     "model": "example-embed-large",
     "provider_request_id": "exm_req_7Q2M41",
     "cost": 38.42,
     "currency": "USD",
     "source": "Provider usage export for the harbor-catalog project key, 2026-09-14, row exm_req_7Q2M41"
   }

   The currency must match the policy; Billr does not convert. Usage that would push the task over its budget is refused, and usage must be recorded before the task is completed.

3. 03Complete the task and read the preview

   complete_task freezes the record and cannot be undone. get_task_billing_preview then returns the amounts a reviewer will approve:

   >_ Expected response, abridgedCopy

   {
     "task": {
       "id": "e3b9d7a2-6f41-4c08-9d25-1a7c5e8b0f63",
       "title": "Catalog re-embedding run",
       "status": "completed",
       "active_seconds": 0,
       "usage_cost": 58.09,
       "invoice_id": null,
       "pricing": {
         "id": "5a8e2c17-4d93-4f6b-a0c2-7e1b9d3f6a48",
         "name": "Harbor & Lane: API usage at cost plus 20%",
         "currency": "USD",
         "hourly_rate": 0,
         "usage_multiplier": 1.2,
         "budget": 150
       }
     },
     "time_amount": 0,
     "usage_amount": 69.71,
     "total": 69.71,
     "currency": "USD",
     "requires_human_review": true,
     "review_url": "https://billr.cc/tasks"
   }

4. 04A person reviews the evidence and approves the draft

   In Task billing, open “Review reported usage sources” on the task and compare each row with the provider's export for the same key and dates. Then choose “Approve costs & create draft invoice”. Only an owner or admin, signed in to the app, can do this; an agent key cannot. The result is INV-1163, a draft for $69.71.

5. 05Bill the human time from time entries

   The hours were logged with log_time during the month. One call drafts them, linking each entry to the invoice so it leaves the unbilled list:

   >_ Tool call, fictional valuesCopy

   create_invoice  {
     "request_id": "6b3e9c2a-8f14-4d70-a5b9-1e7c4a2d8f63",
     "client_name": "Harbor & Lane",
     "issue_date": "2026-09-30",
     "time_entry_ids": [
       "7c2f9a51-3e86-4b17-8d40-6a9e1c3b5f72",
       "2d6b4e83-9a17-4c52-b3e0-8f1a7c5d9e26"
     ]
   }

   The month-end version of this step is Bill a month of unbilled work.

6. 06Review both drafts, then send them yourself

   Nothing in this flow emails the client. Approving a task and drafting an invoice both stop at a draft. Sending is a separate send_invoice call or a send from the app. Be aware that a connection with the send permission (the Billing or Full key profiles, or “Send invoices and estimates” ticked on the consent screen) can email an invoice as soon as it calls that tool, with no extra dashboard step. If you want to review every send yourself, keep agents on Read and draft.

The invoice line has to make sense without a call. Put the period, the basis and where the number came from in the invoice notes, for example:

Embedding API usage for catalog re-embedding run, 1–30 September 2026: $58.09 reported by the provider for the harbor-catalog project key, billed at cost plus 20.00% as agreed. Request-level export available on request.

Keep the provider export for the period. If the client asks, send them the rows behind the charge, not a screenshot of a total. Say “markup” if you agreed a markup; do not describe it as a provider fee.

• The client agreed to this kind of charge, at this markup, before the work.
• The policy matches the agreement: client, currency, hourly rate, multiplier and budget.
• Every usage row has a provider reference and a source you can open again.
• The task's reported cost matches the provider's records for that key and period, or you can explain the difference.
• Every row falls inside the billing period, and none was already billed in an earlier period.
• Nothing is billed twice: no usage both on a task and as an expense, no hours both as time entries and as task time.
• The preview total is the total you expected from the agreement.
• Draft notes and line wording explain the charge in plain terms.
• You know which connection, if any, is allowed to send.

Can I bill AI usage the client never agreed to?

Billr will record whatever you report, but that does not make the charge agreed. If the contract is silent, ask the client before invoicing, or absorb the cost. Whether an unagreed charge is recoverable depends on your contract and local law, which this guide does not cover.

I pay a flat monthly subscription for my coding assistant. Can I pass it on?

A flat subscription fee is not evidence of what any single request cost, so it is not something to report as task usage. Any amount you put on a client is an allocation you chose. Either build it into your rate, or agree a fixed tool fee and bill it as its own line or expense, described as an allocation. Credits drawn from a prepaid balance are different: if the provider records what each request cost, those are reported costs; the top-up purchase itself is not usage.

What about failed or retried calls?

Two separate questions. Whether the provider charged for a failed call is in the provider's own records; bill only what they show, and only if your agreement covers it. On the Billr side, retrying a report with the same request_id returns the original result, and a provider reference can only be recorded once per business and provider, so retries do not add rows.

The provider bills me in USD and the client pays in EUR.

Billr does not convert. Usage must be in the policy's currency, and the invoice follows the policy. Either agree to bill usage in the provider's currency, or agree a conversion rule (which reference rate, which date) and apply it yourself before reporting. That amount is then your conversion, not the provider's figure, so write the original amount, the rate and its date into the source for the reviewer.

The deliverable is fixed-price. Do I add usage on top?

Not unless the agreement says so. Bill the agreed price, for example from an engagement milestone. You can still track your real cost on a task under a policy whose hourly rate and usage multiplier are both 0. Its total is zero, so it records the cost but cannot be invoiced. The blog post on billing a fixed-price coding task covers that case end to end.

Does Billr check the cost against my provider account?

No. Billr stores the reported cost, the provider reference and the source text, and shows them to the reviewer. It does not import provider invoices, read provider dashboards or infer prices from model names. The review step exists because of that.

Can time and usage go on one invoice?

Not through task approval, which creates a draft of its own. Send the two drafts together and reference one in the other’s notes. Retyping the usage onto the time invoice leaves the task approvable, so the same usage could be invoiced a second time.

• Fetch or verify provider costs. Usage is what you or your agent report.
• Convert currencies, or estimate a cost from tokens or model names.
• Count usage against an allowance, or calculate overage.
• Put task usage and time entries on the same draft.
• Let an agent approve pricing or turn a task into an invoice.
• Send anything when a task is approved. Sending is separate, and is only as restricted as the permissions you gave each connection.

The budget is per task, not per month or per client. An agent with write access can create more than one task, so set its instructions accordingly.