Estimates and items

Two things that sit either side of an invoice: a quote you send before the work, and a rate list you bill from once the work is done. Both are in the app and both are exposed to agents over MCP.

Estimates

An estimate is a quote. It uses the same branded template as your invoices and has its own shareable link at /e/<id>, but it never carries a balance, because nothing is owed until it becomes an invoice.

The lifecycle is draft, sent, viewed, then accepted, declined, or expired. An accepted estimate can be converted once, at which point it is marked converted and points at the invoice it produced.

An accepted estimate whose work will be billed in parts can become an engagement instead. Each part of that schedule is then billed by passing its id to create_invoice as engagement_entry_ids, which marks that part invoiced in the same transaction so it can never be billed twice.

create_estimate

Drafts a quote for a client, identified by client_id or client_name. Always created as a draft, the same way create_invoice is.

update_draft_estimate

Changes lines, dates, discount, or notes while the estimate is still a draft. Once it has been sent, it is frozen; create a new one instead.

send_estimate

Emails the estimate to the client with the branded PDF attached. Pass "to" if the client record has no email on file.

list_estimates / get_estimate

Read what is outstanding, and load one in full before editing or converting it so the agent is working from the real current contents.

convert_estimate_to_invoice

Copies the accepted estimate into a new draft invoice, line for line, and marks the estimate converted so it cannot be billed twice.

convert_estimate_to_engagement

Turns the accepted estimate into an agreed total with a payment schedule instead of one invoice, carrying the client, the total and the currency across unchanged. Use it when the work will be billed in parts. A quote becomes an invoice or an engagement, never both.

Try it

Example
Draft an estimate for Harbor & Lane: 12 hours of Consulting and one Technical audit, valid for 30 days. Show it to me before you send it.
Example
Harbor & Lane accepted EST-0210. Turn it into an invoice due in 14 days and leave it as a draft.

Saved items

A saved item is a named rate: a description, a unit, a default rate, and an optional default tax rate. It exists so you do not retype your own prices, and so an agent can bill something without being told what it costs.

Any line on an invoice or an estimate can point at a saved item with item_id or item_name instead of spelling out a description and a rate. Billr fills in the stored description and rate, so this prompt is enough:

Example
Bill Harbor & Lane for 3 hours of Consulting.

Keep item names distinct, because item_name matches on the exact name, case-insensitively. You can still override the rate on an individual line when a client has a different deal.

list_items

Reads the catalog, optionally filtered by a substring of the name. Retired items are hidden unless you ask for them.

create_item

Adds a rate to the catalog: name, rate, and optionally a description, unit, type, and default tax rate.

update_item

Changes a rate, or retires an item without deleting it. Changes apply to future documents only. Anything already issued keeps the rate it was billed at, so this is not the way to correct an invoice; use update_draft_invoice for that.

Sending is a separate permission

Estimates and converted invoices land as drafts, exactly like invoices your agent creates directly. An agent with the default read and draft access cannot send them; one you granted the send permission can deliver them without a dashboard step. Everything an agent creates is tagged so you can see it in the Activity feed under Agents.

Next: Getting paid covers connecting Stripe and testing your checkout before a client ever sees it.

Step-by-step: draft a quote, send it for approval, then convert the accepted one.