Draft an invoice line by line

create_invoice always produces a draft. Give it a client and either written line_items or source ids from logged work; everything else (currency, issue date, due date, notes) has a documented default drawn from the client and business.

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

Who this is for: People billing a fixed scope, a retainer or a one-off amount that was never logged as time or an expense.
Billr capabilities used: create_invoiceget_invoicelist_invoices

What you need first

A client record, because every invoice belongs to one client and one business.
A key with the Read and draft profile; sending later needs the billing profile.
The line descriptions, quantities and rates you want printed.

Step by step

01Pass a unique request_id
request_id is required and makes the call idempotent. If a retry happens after a timeout, reusing the same id with the same input returns the original draft instead of creating a second one.

02Write the lines

Each line needs a description, a quantity and a rate. A line can reference a catalog item by item_name or item_id instead, which copies the stored description and rate.

create_invoice  {
  "request_id": "9e5b2c71-3d68-4a09-8c54-1f7b3e2d6a80",
  "client_name": "Harbor & Lane",
  "line_items": [
    { "description": "Website strategy", "quantity": 1, "rate": 2400 },
    { "description": "Consulting", "quantity": 3, "rate": 150 }
  ],
  "notes": "Payable within 14 days."
}

03Let the defaults fill in the rest
Currency comes from the client, issue_date defaults to today, due_date defaults to the business payment terms, and notes fall back to the business template when you omit them.
04Read the draft back
get_invoice returns the stored lines and totals, and list_invoices with status: "draft" shows what is waiting for review.

Worked example

Fictional account, field names as returned by the server

You say

Invoice Harbor & Lane for the strategy sprint and three hours of consulting.

Your agent calls

create_invoice { "request_id": "9e5b2c71-3d68-4a09-8c54-1f7b3e2d6a80", "client_name": "Harbor & Lane", "line_items": [ { "description": "Website strategy", "quantity": 1, "rate": 2400 }, { "description": "Consulting", "quantity": 3, "rate": 150 } ] }

Expected response, abridged

{
  "summary": "Drafted INV-1150 for Harbor & Lane: $2,850.00",
  "invoice": {
    "invoice_number": "INV-1150",
    "status": "draft",
    "currency": "USD",
    "subtotal": 2850,
    "total": 2850,
    "balance_due": 2850
  }
}

Limits and gotchas

The result is always a draft. Billr never emails a client from create_invoice.
Quantity must be greater than zero; rate may be zero or more. A free line with quantity 1 and rate 0 is valid, a zero quantity is not.
Discounts, tax and shipping are optional fields, but tax applies to the invoice as a whole, not per line.
Written lines and source-linked work cannot be mixed into one line. Choose one source per invoice, or write the line and leave the logged work unbilled.

Troubleshooting

Two drafts appeared for one request: The retry used a new request_id. Reuse the original id and input; if the first call succeeded, it returns that draft.
The total does not match your arithmetic: Check for a discount or tax already stored on the draft, then read the invoice with get_invoice. Amounts are rounded to two decimals by the server.
The invoice came out in the wrong currency: Currency follows the client. Fix the client currency with update_client before drafting, or pass currency explicitly for a deliberate exception.

Sources

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