Guides
26 guides, grouped by what you are trying to do. Each one is a single job, start to finish, checked against the tools Billr actually ships and the client documentation it depends on. The docs explain how Billr works; the guides are how a session gets the work done.
Agents and access
Draft an invoice from a Claude Code session over MCP
Draft an invoice from Claude CodeConnect Billr to Claude Code as a remote HTTP MCP server, then have the session draft an invoice from unbilled work or hand-written lines.Read guideDraft an invoice from Codex using an MCP server entry in config.toml
Draft an invoice from CodexRegister Billr in Codex with a config.toml MCP server entry, keep the key in an environment variable, and draft an invoice from the session.Read guideGive an agent the smallest key profile that does the job
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.Read guide
Clients and catalog
Create a client record an agent can 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.Read guideBill one client in a currency other than the business default
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.Read guideKeep a saved rate list so agents bill the agreed price
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.Read guideKeep several businesses separate under one API key
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.Read guide
Invoices
Write invoice lines directly when no logged work exists
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.Read guideTurn logged time and expenses into drafts, client by client
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.Read guideFix a draft invoice before the client ever sees it
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.Read guideEmail an invoice with the PDF attached
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.Read guideHand a client a payable link without emailing it
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.Read guideRecord money received without marking the invoice fully paid
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.Read guideAnswer "has this been paid" with the ledger, not a guess
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.Read guideFind which invoices are late and how much is behind
Review overdue invoicesUse list_invoices and the overdue flag to see what is late, then revenue_summary for the total that is behind.Read guide
Estimates
Quote work before it starts and keep the quote out of the ledger
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.Read guideChange a quote after a client conversation but before sending
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.Read guideDeliver a quote and let the client accept or decline it
Send an estimate for approvalUse send_estimate to deliver a quote by email, and know how viewing and acceptance show up on the estimate.Read guideTurn an accepted quote into a draft invoice without retyping it
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.Read guide
Time and expenses
Find time and expenses that are not on an invoice yet, then clear them
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.Read guideRecord billable hours while the work is still fresh
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.Read guideFix an hours, rate or client mistake before billing
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.Read guideRecord a client cost that should be rebilled
Track a billable expenseLog an expense against a client with log_expense, choose a category, and know how it reaches an invoice.Read guideKeep client rebills apart from costs the business absorbs
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.Read guide
Tasks, reports and money owed
Track agent work under an approved rate and report provider cost
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.Read guideSummarize invoiced, paid and outstanding totals for a period
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.Read guide
Every guide uses a fictional account for its example, and the expected responses are the field names the server returns. Every guide works the same way on a hosted account and on a self-hosted installation.
Longer walkthroughs
When the job spans several sessions, a quote and a due date, the blog covers it end to end. The guides above stay the narrower reference for a single step.
- How to invoice freelance software development across several coding sessions
- How to turn an accepted project estimate into an invoice without re-entering scope
- How to bill a fixed-price coding task with AI assistance while keeping human approval
- How to close out monthly client billing without missing unbilled hours or expenses
- How to track reimbursable project expenses and include them on a client invoice
- How to follow up on overdue freelance invoices without sending duplicate reminders