Draft an estimate for work not yet agreed

create_estimate drafts a quote for a client and never touches the money side: an estimate has no balance, and list_estimates answers "what quotes are outstanding". Use it before work starts, and create_invoice once work is delivered.

Written and reviewed by the Billr team. Published 2026-09-20, last reviewed 2026-09-20.

Who this is for: People who price a project before they build it, or who need a signed-off scope before starting.
Billr capabilities used: create_estimateget_estimatelist_estimates

What you need first

A client record, because an estimate belongs to one client and one business.
A key with the Read and draft profile.
The scope, either as written lines or as saved items from your catalog.

Step by step

01Write the lines once

line_items is required and each line needs a description, quantity and rate. A line may reference item_name or item_id instead, which pulls the stored description and rate.

create_estimate  {
  "request_id": "2e6b4d18-9c37-4a55-8f12-5d3a7c9b0e26",
  "client_name": "Harbor & Lane",
  "line_items": [
    { "description": "Discovery", "quantity": 1, "rate": 1200 },
    { "description": "Content migration", "quantity": 1, "rate": 3400 }
  ],
  "terms": "Valid for 30 days. 50% up front."
}

02Set the dates deliberately
issue_date defaults to today and expiry_date is optional. An expiry is what lets an old quote be treated as expired rather than silently converted later.
03Add adjustments only if you mean them
discount_type with discount_value, tax_rate and shipping_amount behave the same way they do on an invoice, so a quote and the invoice it becomes can match.
04Read it back
get_estimate returns the stored lines, totals, status and the estimate link, and list_estimates filters by status, including accepted and converted. The link is yours to check while the quote is a draft; the public page refuses drafts, so a client cannot view or accept it until it is sent.

Worked example

Fictional account, field names as returned by the server

You say

Quote Harbor & Lane $1,200 for discovery and $3,400 for the migration.

Your agent calls

create_estimate { "request_id": "2e6b4d18-9c37-4a55-8f12-5d3a7c9b0e26", "client_name": "Harbor & Lane", "line_items": [ { "description": "Discovery", "quantity": 1, "rate": 1200 }, { "description": "Content migration", "quantity": 1, "rate": 3400 } ] }

Expected response, abridged

{
  "summary": "Drafted estimate EST-0213 for Harbor & Lane: $4,600.00",
  "estimate": {
    "estimate_number": "EST-0213",
    "status": "draft",
    "currency": "USD",
    "total": 4600
  }
}

Limits and gotchas

Estimates never carry a balance, and no tool reports money owed for one.
A draft is not emailed, and its public page does not serve drafts, so a client cannot view or answer it until send_estimate delivers it.
line_items is required even when the scope is obvious; there is no amount-only estimate.
An estimate does not reserve a number in the invoice series; the invoice gets its own number when you convert.

Troubleshooting

The quote came out in the wrong currency: Estimates take the client currency, the same rule as invoices. Fix the client first with update_client if needed.
A catalog line was not priced as expected: The saved item was renamed or the name was ambiguous. Run list_items and pass item_id for an exact match.
The client never saw the quote: A draft estimate is not delivered. Send it with send_estimate, or share the link from get_estimate.

Sources

Reviewed 2026-09-20 against Billr's own tool implementations and the client documentation linked above.