Billr docs
Everything you need to connect an agent to Billr, from your first connection to running a month-end invoice draft, quoting work, and collecting payment. Start with Get started if you're new, or jump straight to a guide below. Still deciding whether Billr fits? The MCP server overview explains what an agent can do, where approval sits, and hosted versus self-hosted.
Get started
Connect an agent, check it with a read-only request, and review its first invoice draft.
Read guideTask billing
Agree on rates, track active work and provider costs, then review the bill.
Read guideConnect your agent
Point Claude Code, claude.ai, or any MCP-enabled agent at Billr, and see all 53 tools.
Read guideAPI keys
Create and manage keys for agents that talk to Billr directly.
Read guideEstimates and items
Quote work, convert an accepted quote, and bill from a saved rate by name.
Read guideEngagements
Record an agreed total, split it into a schedule, and bill each part when it is due.
Read guideGetting paid
Connect Stripe, test your checkout, and let agents check payment status.
Read guideRecipes
Ready-to-run prompts and scripts for common billing workflows.
Read guideTool reference
Every one of the 53 tools, grouped by job, with the key scope each one needs.
Read guideSelf-hosting FAQ
Answers on running the open-source Billr application yourself.
Read guideStep-by-step guides
One job per page, from connecting a specific client to clearing the work that is not on an invoice yet.
- Draft an invoice from Claude CodeConnect Billr to Claude Code as a remote HTTP MCP server with a scoped key kept out of shell history, confirm it with a read-only request, then draft an invoice you review before sending.
- Draft an invoice from CodexRegister Billr in Codex with a config.toml MCP server entry, keep a scoped key in an environment variable, confirm it with a read-only request, and draft an invoice from logged work.
- Find unbilled work before you invoiceUse list_unbilled to see billable time and expenses grouped by client, understand the flags it raises, and turn the list into a draft invoice.
- Add your first clientCreate a client with create_client, add the details that print on documents, and confirm the record before an invoice exists.
- Set the currency you bill a client inChoose a client currency with create_client or update_client, and understand how currency follows a client into invoices, estimates and source-linked work.
- Build a reusable catalog of ratesCreate saved items with create_item, correct them with update_item, and bill them by name so an agent never invents a price.
- Work across more than one businessUse list_businesses to see what a key can reach, and pass business_id whenever one key covers more than one business.
- Scope what an agent is allowed to doChoose between Read only, Read and draft, Billing and Full key profiles, and know exactly which tools each one unlocks.
- Draft an invoice line by lineCreate a draft from written line items, set the dates and terms, and know what the server fills in for you.
- Bill a month of logged workRun list_unbilled once, then create one draft per client from the source ids, with the amounts the server computes.
- Correct a draft before you send itUse update_draft_invoice to replace lines or adjust dates, notes, discounts, tax and shipping while the invoice is still a draft.
- Send an invoice to a clientUse send_invoice to move a draft to sent, with the PDF attached, and know which statuses refuse to send.
- Share an invoice link instead of emailing itGet the public invoice URL and PDF with get_invoice_link, and understand what opening that link does to the invoice status.
- Record a partial paymentLog an amount that is less than the balance, choose the payment method, and let the server set partial or paid from the balance.
- Reconcile what has actually been paidRead the payment ledger beside the stored balance, spot a mismatch before quoting a number, and find invoices that are still unpaid.
- Review overdue invoicesUse list_invoices and the overdue flag to see what is late, then revenue_summary for the total that is behind.
- Draft an estimate for work not yet agreedCreate a quote with create_estimate, price it from written lines or your catalog, and keep it separate from anything owed.
- Revise a quote before the client sees itUpdate a draft estimate with update_draft_estimate, and know why a sent quote has to be replaced rather than edited.
- Send an estimate for approvalUse send_estimate to deliver a quote by email, and know how viewing and acceptance show up on the estimate.
- Convert an accepted estimate into an invoiceCall convert_estimate_to_invoice on an accepted quote, understand the refusal cases, and know why a retry is safe.
- Log time from an agent sessionCall log_time with a request_id, decide whether to include a rate, and keep hours inside the limits the server enforces.
- Correct logged time before it is billedUse update_time_entry to fix hours, rate, description, date, client or billable flag, and delete_time_entry while the entry is still unbilled.
- Track a billable expenseLog an expense against a client with log_expense, choose a category, and know how it reaches an invoice.
- Separate reimbursable and non-billable costsUse the billable flag and update_expense to keep client rebills out of your own overhead, and read both sides with list_expenses.
- Run a billable task from start to reviewCreate a task against a human-approved pricing policy, run it through start and pause, report usage, and hand it to human billing review.
- Review revenue and what is still outstandingUse revenue_summary for a period, read the per-currency output when a business bills in more than one currency, and see the top clients.
- How to bill clients for AI usageChoose between pass-through, markup, an allowance or a fixed price for AI API costs, agree it up front, and invoice it with evidence. Includes a worked example.