Revise a quote before the client sees it

update_draft_estimate works only while the estimate is a draft. Passing line_items replaces every line and recomputes totals; passing only dates, terms, notes, discount, tax or shipping changes those fields.

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

Who this is for: Anyone negotiating scope before the quote goes out.
Billr capabilities used: update_draft_estimateget_estimate

What you need first

The estimate id, which list_estimates returns with status draft.
A key with the Read and draft profile.
The agreed numbers, because replacing lines discards the previous ones.

Step by step

01Read the current quote
get_estimate returns the stored lines and totals. Revise against real contents, not against the version in your memory.

02Replace the lines when the scope changed

Supplying line_items replaces all of them and recomputes the totals in one call.

update_draft_estimate  {
  "estimate_id": "a4f1c8d2-6b39-4e07-9d51-2c8a6f3b1e94",
  "line_items": [
    { "description": "Discovery", "quantity": 1, "rate": 1200 },
    { "description": "Content migration", "quantity": 1, "rate": 2900 }
  ],
  "expiry_date": "2026-10-31"
}

03Adjust terms without touching the lines
terms, notes, issue_date and expiry_date change on their own and leave the money alone. Discount, tax and shipping also change on their own, but they recompute the total, so read the returned figures. Changing only discount_type reinterprets the stored value, so pass both discount fields when the meaning changes.
04Check the status afterwards
A successful update returns the estimate with status still draft. If the response says another status, the quote had already been sent and the edit was refused.

Worked example

Fictional account, field names as returned by the server

You say

Drop the migration to $2,900 and push the expiry to the end of October.

Your agent calls

get_estimate { "estimate_id": "a4f1c8d2-6b39-4e07-9d51-2c8a6f3b1e94" }
update_draft_estimate { "estimate_id": "a4f1c8d2-6b39-4e07-9d51-2c8a6f3b1e94", "line_items": [ { "description": "Discovery", "quantity": 1, "rate": 1200 }, { "description": "Content migration", "quantity": 1, "rate": 2900 } ], "expiry_date": "2026-10-31" }

Expected response, abridged

{
  "summary": "Updated draft estimate EST-0213: $4,100.00",
  "estimate": {
    "estimate_number": "EST-0213",
    "status": "draft",
    "total": 4100,
    "expiry_date": "2026-10-31"
  }
}

Limits and gotchas

Sent, accepted, declined, expired and converted estimates are all closed to editing, because the client has seen those numbers.
There is no partial line edit: replacing lines is all-or-nothing.
A sent quote is not silently rewritten. Create a new estimate for a changed scope.
Revising a draft does not change its number, so a client who saw the number still recognises it.

Troubleshooting

"Only draft estimates can be edited": The quote was already sent. Create a fresh estimate with the new numbers and send that, so the client is never confused by a changed document.
Totals did not change: Check that line_items was actually supplied. Without it, the call only touches the metadata fields you passed.
The expiry date is wrong by a day: Dates are plain calendar dates in YYYY-MM-DD. Check the timezone assumptions in the prompt rather than the stored value.

Sources

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