How to turn an accepted project estimate into an invoice without re-entering scope

The project is agreed. The scope lives in a quote the client already read and accepted, with a weekly rate, an audit line and an amount of launch support. Then invoicing time arrives and someone rebuilds that list by hand in a second document.

That is the step where drift happens. A line gets retyped as an approximate figure, a discount is silently dropped, or the total changes by a few hundred dollars because the rounding was recomputed rather than carried. Both documents describe the same agreement, so they should not be able to disagree.

Billr keeps estimates and invoices as separate records with their own numbering, and conversion is the one operation that moves scope from the first into the second. After it, the estimate reads "converted" and points at the invoice, and the invoice carries the same lines.

Start by reading the estimate rather than trusting memory. list_estimates returns quotes with their status, total and the invoice id if one was already produced; get_estimate returns the full record including the line items and the client.

Statuses matter for what happens next. accepted is the state you want. Sent and viewed mean the client has the quote but has not formally accepted it in Billr, and conversion will still work while the summary tells you the estimate was not formally accepted. declined and expired are refused outright. converted means an invoice already exists. If the client has not replied yet, send the estimate and wait for that recorded acceptance instead.

list_estimates  { "status": "accepted", "client_id": "9f2a4d18-3b7c-4a6e-8f0d-1c5b2e9a7d44" }
get_estimate    { "estimate_id": "a41d7e93-2c68-4b05-8f71-3e9a5c1d7b26" }

Estimates and their statuses

Billr demo data, fictional throughout. View full size

One call does the whole move: convert_estimate_to_invoice takes the estimate id plus the two dates, then claims the estimate, allocates the next invoice number, writes the invoice and its line items, and links everything together inside a single transaction.

Because the claim happens first, a retried request cannot produce a second invoice. If another call already converted the estimate, this call writes nothing and returns the existing invoice with already_converted: true, which is a success rather than an error.

convert_estimate_to_invoice  {
  "estimate_id": "a41d7e93-2c68-4b05-8f71-3e9a5c1d7b26",
  "issue_date": "2026-09-21",
  "due_date": "2026-10-21"
}

{
  "summary": "Converted estimate EST-1042 into draft invoice INV-1152: $5,000.00. Call send_invoice to deliver it.",
  "already_converted": false,
  "invoice": {
    "id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11",
    "invoice_number": "INV-1152",
    "status": "draft",
    "issue_date": "2026-09-21",
    "due_date": "2026-10-21",
    "currency": "USD",
    "subtotal": 5000,
    "total": 5000,
    "balance_due": 5000,
    "line_items": [
      {
        "description": "Discovery and technical audit",
        "quantity": 1,
        "rate": 900
      },
      {
        "description": "Implementation sprint (weekly)",
        "quantity": 3,
        "rate": 1200
      },
      {
        "description": "Launch support",
        "quantity": 1,
        "rate": 500
      }
    ]
  },
  "estimate": {
    "id": "a41d7e93-2c68-4b05-8f71-3e9a5c1d7b26",
    "estimate_number": "EST-1042",
    "status": "converted",
    "converted_invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11"
  },
  "app_url": "/invoices/6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11"
}

• Line items and totals: the invoice copies the estimate lines, so the amounts should match the accepted quote exactly.
• Dates: issue date and due date are on the invoice, not the estimate, and they come from the call or from the business default term.
• Currency: invoices and their source work must agree on currency. Billr does not convert between them.
• Numbers: the estimate keeps its own number, the invoice gets the next invoice number, and both records link to each other afterwards.

If the dates are wrong, fix the draft with update_draft_invoice rather than converting again. If the scope genuinely changed after acceptance, amend the draft lines and note why, or issue a separate change-order invoice for the new work. What you should not do is convert a second time and end up with two drafts describing one agreement.

One detail is easy to miss: nothing about the invoice changes just because the scope was agreed. The convert an accepted estimate guide follows the same call, and correcting the draft is the step that makes the numbers match what the client actually owes today.

Plenty of projects are not billed in one go: a deposit up front, a milestone on delivery, the balance on acceptance. Conversion copies the whole accepted scope into one invoice, so it is the wrong tool for taking a third of it.

For a deposit or milestone, draft an invoice for that stage with create_invoice and a hand-written line_items entry that names the stage. Keep the estimate unconverted until the final invoice, or convert it for the closing balance.

If you convert after part of the work was already invoiced, conversion does not subtract anything. It copies every line from the quote, and adding a note does not change the amount. Reconcile the draft yourself before it is sent: total the amounts already invoiced against this quote, then replace the draft lines so the invoice covers only what is still outstanding.

update_draft_invoice  {
  "invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11",
  "line_items": [
    { "description": "Implementation sprint (weekly), less deposit already invoiced", "quantity": 1, "rate": 3500 }
  ],
  "notes": "Balance of EST-1042. Deposit of $1,500.00 was billed on INV-1130."
}

• Declined, expired and already-converted estimates are the three states that change the outcome, and only the last one is not an error.
• An estimate with no line items cannot be converted. There would be nothing to invoice.
• The conversion copy is one invoice, so there is no partial conversion tool.
• Conversion does not send anything. Delivery is send_invoice, or the Send action in the app, and it is the step that needs explicit permission.