Correct a draft before you send it

update_draft_invoice only works while the invoice status is draft. Passing line_items replaces every existing line and recomputes totals; passing only dates, notes, discount, tax or shipping changes just those fields.

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

Who this is for: Anyone reviewing an agent-created draft before it goes to a client.
Billr capabilities used: update_draft_invoiceget_invoice

What you need first

The invoice id of a draft. list_invoices with status: "draft" lists them.
A key with the Read and draft profile; correcting is a write.
The final numbers, because replacing lines recomputes every total from scratch.

Step by step

01Read the current draft first
get_invoice returns the stored lines, totals, notes and dates. Editing against assumed contents is how a valid correction turns into a wrong invoice.

02Replace the lines when the numbers change

Passing line_items replaces ALL existing lines and recomputes subtotal, discount, tax and total. Omit it when you only want to adjust metadata.

update_draft_invoice  {
  "invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11",
  "line_items": [
    { "description": "Website strategy", "quantity": 1, "rate": 2200 },
    { "description": "Consulting", "quantity": 3, "rate": 150 }
  ],
  "due_date": "2026-10-15",
  "notes": "Payable within 21 days."
}

03Adjust dates, notes or an adjustment field
issue_date, due_date, notes, discount_type with discount_value, tax_rate and shipping_amount can be changed on their own. Changing discount_type alone reinterprets the stored value, so pass both fields when the meaning changes.
04Re-read before sending
Check the returned invoice: status should still be draft, the total should match the lines, and any source-linked work stays attached to the same draft.

Worked example

Fictional account, field names as returned by the server

You say

The strategy sprint was $2,200, not $2,400. Fix the draft.

Your agent calls

get_invoice { "invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11" }
update_draft_invoice { "invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11", "line_items": [ { "description": "Website strategy", "quantity": 1, "rate": 2200 }, { "description": "Consulting", "quantity": 3, "rate": 150 } ] }

Expected response, abridged

{
  "summary": "Updated draft invoice INV-1150: $2,650.00",
  "invoice": {
    "invoice_number": "INV-1150",
    "status": "draft",
    "subtotal": 2650,
    "total": 2650,
    "balance_due": 2650
  }
}

Limits and gotchas

Only drafts can be edited. A sent invoice answers with its status and tells you to cancel and recreate instead.
Replacing lines discards the previous ones entirely; there is no partial edit of a single line.
Attached time and expenses stay linked to the draft, and those source rows cannot be edited while the link exists. The invoice lines themselves are whatever update_draft_invoice sets, so correct the lines on the draft.
Correcting a draft does not change the estimate it came from, which stays converted, and cancelling the draft does not release attached work.

Troubleshooting

update_draft_invoice refuses with a status message: The invoice is no longer a draft. Correct forward with a new document rather than rewriting something the client has received.
Your line changes did not appear: A source-linked invoice rebuilds its lines from logged work. Edit the time entries or expenses before drafting instead.
The discount is now enormous: A stored fixed discount was reinterpreted as a percentage, or the reverse. Pass discount_type and discount_value together whenever you change the meaning.

Sources

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